diff options
Diffstat (limited to 'upstream/fedora-40/man1/ld.1')
| -rw-r--r-- | upstream/fedora-40/man1/ld.1 | 3532 |
1 files changed, 3532 insertions, 0 deletions
diff --git a/upstream/fedora-40/man1/ld.1 b/upstream/fedora-40/man1/ld.1 new file mode 100644 index 00000000..89d42f35 --- /dev/null +++ b/upstream/fedora-40/man1/ld.1 @@ -0,0 +1,3532 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "LD 1" +.TH LD 1 2024-02-12 binutils-2.41 "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ld \- The GNU linker +.SH SYNOPSIS +.IX Header "SYNOPSIS" +ld [\fBoptions\fR] \fIobjfile\fR ... +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBld\fR combines a number of object and archive files, relocates +their data and ties up symbol references. Usually the last step in +compiling a program is to run \fBld\fR. +.PP +\&\fBld\fR accepts Linker Command Language files written in +a superset of AT&T's Link Editor Command Language syntax, +to provide explicit and total control over the linking process. +.PP +This man page does not describe the command language; see the +\&\fBld\fR entry in \f(CW\*(C`info\*(C'\fR for full details on the command +language and on other aspects of the GNU linker. +.PP +This version of \fBld\fR uses the general purpose BFD libraries +to operate on object files. This allows \fBld\fR to read, combine, and +write object files in many different formats\-\-\-for example, COFF or +\&\f(CW\*(C`a.out\*(C'\fR. Different formats may be linked together to produce any +available kind of object file. +.PP +Aside from its flexibility, the GNU linker is more helpful than other +linkers in providing diagnostic information. Many linkers abandon +execution immediately upon encountering an error; whenever possible, +\&\fBld\fR continues executing, allowing you to identify other errors +(or, in some cases, to get an output file in spite of the error). +.PP +The GNU linker \fBld\fR is meant to cover a broad range of situations, +and to be as compatible as possible with other linkers. As a result, +you have many choices to control its behavior. +.SH OPTIONS +.IX Header "OPTIONS" +The linker supports a plethora of command-line options, but in actual +practice few of them are used in any particular context. +For instance, a frequent use of \fBld\fR is to link standard Unix +object files on a standard, supported Unix system. On such a system, to +link a file \f(CW\*(C`hello.o\*(C'\fR: +.PP +.Vb 1 +\& ld \-o <output> /lib/crt0.o hello.o \-lc +.Ve +.PP +This tells \fBld\fR to produce a file called \fIoutput\fR as the +result of linking the file \f(CW\*(C`/lib/crt0.o\*(C'\fR with \f(CW\*(C`hello.o\*(C'\fR and +the library \f(CW\*(C`libc.a\*(C'\fR, which will come from the standard search +directories. (See the discussion of the \fB\-l\fR option below.) +.PP +Some of the command-line options to \fBld\fR may be specified at any +point in the command line. However, options which refer to files, such +as \fB\-l\fR or \fB\-T\fR, cause the file to be read at the point at +which the option appears in the command line, relative to the object +files and other file options. Repeating non-file options with a +different argument will either have no further effect, or override prior +occurrences (those further to the left on the command line) of that +option. Options which may be meaningfully specified more than once are +noted in the descriptions below. +.PP +Non-option arguments are object files or archives which are to be linked +together. They may follow, precede, or be mixed in with command-line +options, except that an object file argument may not be placed between +an option and its argument. +.PP +Usually the linker is invoked with at least one object file, but you can +specify other forms of binary input files using \fB\-l\fR, \fB\-R\fR, +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 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 +permits the linker to link against a file which appears to be an object +or an archive, but actually merely defines some symbol values, or uses +\&\f(CW\*(C`INPUT\*(C'\fR or \f(CW\*(C`GROUP\*(C'\fR to load other objects. Specifying a +script in this way merely augments the main linker script, with the +extra commands placed after the main script; use the \fB\-T\fR option +to replace the default linker script entirely, but note the effect of +the \f(CW\*(C`INSERT\*(C'\fR command. +.PP +For options whose names are a single letter, +option arguments must either follow the option letter without intervening +whitespace, or be given as separate arguments immediately following the +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 +this rule. Multiple letter options that start with a lower case 'o' can +only be preceded by two dashes. This is to reduce confusion with the +\&\fB\-o\fR option. So for example \fB\-omagic\fR sets the output file +name to \fBmagic\fR whereas \fB\-\-omagic\fR sets the NMAGIC flag on the +output. +.PP +Arguments to multiple-letter options must either be separated from the +option name by an equals sign, or be given as separate arguments +immediately following the option that requires them. For example, +\&\fB\-\-trace\-symbol foo\fR and \fB\-\-trace\-symbol=foo\fR are equivalent. +Unique abbreviations of the names of multiple-letter options are +accepted. +.PP +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 +.Vb 1 +\& gcc \-Wl,\-\-start\-group foo.o bar.o \-Wl,\-\-end\-group +.Ve +.PP +This is important, because otherwise the compiler driver program may +silently drop the linker options, resulting in a bad link. Confusion +may also arise when passing options that require values through a +driver, as the use of a space between option and argument acts as +a separator, and causes the driver to pass only the option to the linker +and the argument to the compiler. In this case, it is simplest to use +the joined forms of both single\- and multiple-letter options, such as: +.PP +.Vb 1 +\& gcc foo.o bar.o \-Wl,\-eENTRY \-Wl,\-Map=a.map +.Ve +.PP +Here is a table of the generic command-line switches accepted by the GNU +linker: +.IP \fB@\fR\fIfile\fR 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.IP "\fB\-a\fR \fIkeyword\fR" 4 +.IX Item "-a keyword" +This option is supported for HP/UX compatibility. The \fIkeyword\fR +argument must be one of the strings \fBarchive\fR, \fBshared\fR, or +\&\fBdefault\fR. \fB\-aarchive\fR is functionally equivalent to +\&\fB\-Bstatic\fR, and the other two keywords are functionally equivalent +to \fB\-Bdynamic\fR. This option may be used any number of times. +.IP "\fB\-\-audit\fR \fIAUDITLIB\fR" 4 +.IX Item "--audit AUDITLIB" +Adds \fIAUDITLIB\fR to the \f(CW\*(C`DT_AUDIT\*(C'\fR entry of the dynamic section. +\&\fIAUDITLIB\fR is not checked for existence, nor will it use the DT_SONAME +specified in the library. If specified multiple times \f(CW\*(C`DT_AUDIT\*(C'\fR +will contain a colon separated list of audit interfaces to use. If the linker +finds an object with an audit entry while searching for shared libraries, +it will add a corresponding \f(CW\*(C`DT_DEPAUDIT\*(C'\fR entry in the output file. +This option is only meaningful on ELF platforms supporting the rtld-audit +interface. +.IP "\fB\-b\fR \fIinput-format\fR" 4 +.IX Item "-b input-format" +.PD 0 +.IP \fB\-\-format=\fR\fIinput-format\fR 4 +.IX Item "--format=input-format" +.PD +\&\fBld\fR may be configured to support more than one kind of object +file. If your \fBld\fR is configured this way, you can use the +\&\fB\-b\fR option to specify the binary format for input object files +that follow this option on the command line. Even when \fBld\fR is +configured to support alternative object formats, you don't usually need +to specify this, as \fBld\fR should be configured to expect as a +default input format the most usual format on each machine. +\&\fIinput-format\fR is a text string, the name of a particular format +supported by the BFD libraries. (You can list the available binary +formats with \fBobjdump \-i\fR.) +.Sp +You may want to use this option if you are linking files with an unusual +binary format. You can also use \fB\-b\fR to switch formats explicitly (when +linking object files of different formats), by including +\&\fB\-b\fR \fIinput-format\fR before each group of object files in a +particular format. +.Sp +The default format is taken from the environment variable +\&\f(CW\*(C`GNUTARGET\*(C'\fR. +.Sp +You can also define the input format from a script, using the command +\&\f(CW\*(C`TARGET\*(C'\fR; +.IP "\fB\-c\fR \fIMRI-commandfile\fR" 4 +.IX Item "-c MRI-commandfile" +.PD 0 +.IP \fB\-\-mri\-script=\fR\fIMRI-commandfile\fR 4 +.IX Item "--mri-script=MRI-commandfile" +.PD +For compatibility with linkers produced by MRI, \fBld\fR accepts script +files written in an alternate, restricted command language, described in +the MRI Compatible Script Files section of GNU ld documentation. +Introduce MRI script files with +the option \fB\-c\fR; use the \fB\-T\fR option to run linker +scripts written in the general-purpose \fBld\fR scripting language. +If \fIMRI-cmdfile\fR does not exist, \fBld\fR looks for it in the directories +specified by any \fB\-L\fR options. +.IP \fB\-d\fR 4 +.IX Item "-d" +.PD 0 +.IP \fB\-dc\fR 4 +.IX Item "-dc" +.IP \fB\-dp\fR 4 +.IX Item "-dp" +.PD +These three options are equivalent; multiple forms are supported for +compatibility with other linkers. They assign space to common symbols +even if a relocatable output file is specified (with \fB\-r\fR). The +script command \f(CW\*(C`FORCE_COMMON_ALLOCATION\*(C'\fR has the same effect. +.IP "\fB\-\-depaudit\fR \fIAUDITLIB\fR" 4 +.IX Item "--depaudit AUDITLIB" +.PD 0 +.IP "\fB\-P\fR \fIAUDITLIB\fR" 4 +.IX Item "-P AUDITLIB" +.PD +Adds \fIAUDITLIB\fR to the \f(CW\*(C`DT_DEPAUDIT\*(C'\fR entry of the dynamic section. +\&\fIAUDITLIB\fR is not checked for existence, nor will it use the DT_SONAME +specified in the library. If specified multiple times \f(CW\*(C`DT_DEPAUDIT\*(C'\fR +will contain a colon separated list of audit interfaces to use. This +option is only meaningful on ELF platforms supporting the rtld-audit interface. +The \-P option is provided for Solaris compatibility. +.IP \fB\-\-enable\-linker\-version\fR 4 +.IX Item "--enable-linker-version" +Enables the \f(CW\*(C`LINKER_VERSION\*(C'\fR linker script directive, described +in \fBOutput Section Data\fR. If this directive is used in a linker +script and this option has been enabled then a string containing the +linker version will be inserted at the current point. +.Sp +Note \- this location of this option on the linker command line is +significant. It will only affect linker scripts that come after it on +the command line, or which are built into the linker. +.IP \fB\-\-disable\-linker\-version\fR 4 +.IX Item "--disable-linker-version" +Disables the \f(CW\*(C`LINKER_VERSION\*(C'\fR linker script directive, so that it +does not insert a version string. This is the default. +.IP \fB\-\-enable\-non\-contiguous\-regions\fR 4 +.IX Item "--enable-non-contiguous-regions" +This option avoids generating an error if an input section does not +fit a matching output section. The linker tries to allocate the input +section to subseque nt matching output sections, and generates an +error only if no output section is large enough. This is useful when +several non-contiguous memory regions are available and the input +section does not require a particular one. The order in which input +sections are evaluated does not change, for instance: +.Sp +.Vb 10 +\& MEMORY { +\& MEM1 (rwx) : ORIGIN = 0x1000, LENGTH = 0x14 +\& MEM2 (rwx) : ORIGIN = 0x1000, LENGTH = 0x40 +\& MEM3 (rwx) : ORIGIN = 0x2000, LENGTH = 0x40 +\& } +\& SECTIONS { +\& mem1 : { *(.data.*); } > MEM1 +\& mem2 : { *(.data.*); } > MEM2 +\& mem3 : { *(.data.*); } > MEM3 +\& } +\& +\& with input sections: +\& .data.1: size 8 +\& .data.2: size 0x10 +\& .data.3: size 4 +\& +\& results in .data.1 affected to mem1, and .data.2 and .data.3 +\& affected to mem2, even though .data.3 would fit in mem3. +.Ve +.Sp +This option is incompatible with INSERT statements because it changes +the way input sections are mapped to output sections. +.IP \fB\-\-enable\-non\-contiguous\-regions\-warnings\fR 4 +.IX Item "--enable-non-contiguous-regions-warnings" +This option enables warnings when +\&\f(CW\*(C`\-\-enable\-non\-contiguous\-regions\*(C'\fR allows possibly unexpected +matches in sections mapping, potentially leading to silently +discarding a section instead of failing because it does not fit any +output region. +.IP "\fB\-e\fR \fIentry\fR" 4 +.IX Item "-e entry" +.PD 0 +.IP \fB\-\-entry=\fR\fIentry\fR 4 +.IX Item "--entry=entry" +.PD +Use \fIentry\fR as the explicit symbol for beginning execution of your +program, rather than the default entry point. If there is no symbol +named \fIentry\fR, the linker will try to parse \fIentry\fR as a number, +and use that as the entry address (the number will be interpreted in +base 10; you may use a leading \fB0x\fR for base 16, or a leading +\&\fB0\fR for base 8). +.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 +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. This option is available only for the i386 PE targeted +port of the linker and for ELF targeted ports. For i386 PE, symbols +explicitly listed in a .def file are still exported, regardless of this +option. For ELF targeted ports, symbols affected by this option will +be treated as hidden. +.IP "\fB\-\-exclude\-modules\-for\-implib\fR \fImodule\fR\fB,\fR\fImodule\fR\fB,...\fR" 4 +.IX Item "--exclude-modules-for-implib module,module,..." +Specifies a list of object files or archive members, from which symbols +should not be automatically exported, but which should be copied wholesale +into the import library being generated during the link. The module names +may be delimited by commas or colons, and must match exactly the filenames +used by \fBld\fR to open the files; for archive members, this is simply +the member name, but for object files the name listed must include and +match precisely any path used to specify the input file on the linker's +command-line. This option is available only for the i386 PE targeted port +of the linker. Symbols explicitly listed in a .def file are still exported, +regardless of this option. +.IP \fB\-E\fR 4 +.IX Item "-E" +.PD 0 +.IP \fB\-\-export\-dynamic\fR 4 +.IX Item "--export-dynamic" +.IP \fB\-\-no\-export\-dynamic\fR 4 +.IX Item "--no-export-dynamic" +.PD +When creating a dynamically linked executable, using the \fB\-E\fR +option or the \fB\-\-export\-dynamic\fR option causes the linker to add +all symbols to the dynamic symbol table. The dynamic symbol table is the +set of symbols which are visible from dynamic objects at run time. +.Sp +If you do not use either of these options (or use the +\&\fB\-\-no\-export\-dynamic\fR option to restore the default behavior), the +dynamic symbol table will normally contain only those symbols which are +referenced by some dynamic object mentioned in the link. +.Sp +If you use \f(CW\*(C`dlopen\*(C'\fR to load a dynamic object which needs to refer +back to the symbols defined by the program, rather than some other +dynamic object, then you will probably need to use this option when +linking the program itself. +.Sp +You can also use the dynamic list to control what symbols should +be added to the dynamic symbol table if the output format supports it. +See the description of \fB\-\-dynamic\-list\fR. +.Sp +Note that this option is specific to ELF targeted ports. PE targets +support a similar function to export all symbols from a DLL or EXE; see +the description of \fB\-\-export\-all\-symbols\fR below. +.IP \fB\-\-export\-dynamic\-symbol=\fR\fIglob\fR 4 +.IX Item "--export-dynamic-symbol=glob" +When creating a dynamically linked executable, symbols matching +\&\fIglob\fR will be added to the dynamic symbol table. When creating a +shared library, references to symbols matching \fIglob\fR will not be +bound to the definitions within the shared library. This option is a +no-op when creating a shared library and \fB\-Bsymbolic\fR or +\&\fB\-\-dynamic\-list\fR are not specified. This option is only meaningful +on ELF platforms which support shared libraries. +.IP \fB\-\-export\-dynamic\-symbol\-list=\fR\fIfile\fR 4 +.IX Item "--export-dynamic-symbol-list=file" +Specify a \fB\-\-export\-dynamic\-symbol\fR for each pattern in the file. +The format of the file is the same as the version node without +scope and node name. See \fBVERSION\fR for more information. +.IP \fB\-EB\fR 4 +.IX Item "-EB" +Link big-endian objects. This affects the default output format. +.IP \fB\-EL\fR 4 +.IX Item "-EL" +Link little-endian objects. This affects the default output format. +.IP "\fB\-f\fR \fIname\fR" 4 +.IX Item "-f name" +.PD 0 +.IP \fB\-\-auxiliary=\fR\fIname\fR 4 +.IX Item "--auxiliary=name" +.PD +When creating an ELF shared object, set the internal DT_AUXILIARY field +to the specified name. This tells the dynamic linker that the symbol +table of the shared object should be used as an auxiliary filter on the +symbol table of the shared object \fIname\fR. +.Sp +If you later link a program against this filter object, then, when you +run the program, the dynamic linker will see the DT_AUXILIARY field. If +the dynamic linker resolves any symbols from the filter object, it will +first check whether there is a definition in the shared object +\&\fIname\fR. If there is one, it will be used instead of the definition +in the filter object. The shared object \fIname\fR need not exist. +Thus the shared object \fIname\fR may be used to provide an alternative +implementation of certain functions, perhaps for debugging or for +machine-specific performance. +.Sp +This option may be specified more than once. The DT_AUXILIARY entries +will be created in the order in which they appear on the command line. +.IP "\fB\-F\fR \fIname\fR" 4 +.IX Item "-F name" +.PD 0 +.IP \fB\-\-filter=\fR\fIname\fR 4 +.IX Item "--filter=name" +.PD +When creating an ELF shared object, set the internal DT_FILTER field to +the specified name. This tells the dynamic linker that the symbol table +of the shared object which is being created should be used as a filter +on the symbol table of the shared object \fIname\fR. +.Sp +If you later link a program against this filter object, then, when you +run the program, the dynamic linker will see the DT_FILTER field. The +dynamic linker will resolve symbols according to the symbol table of the +filter object as usual, but it will actually link to the definitions +found in the shared object \fIname\fR. Thus the filter object can be +used to select a subset of the symbols provided by the object +\&\fIname\fR. +.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 GNU 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 GNU linker will ignore the \fB\-F\fR option when not +creating an ELF shared object. +.IP \fB\-fini=\fR\fIname\fR 4 +.IX Item "-fini=name" +When creating an ELF executable or shared object, call NAME when the +executable or shared object is unloaded, by setting DT_FINI to the +address of the function. By default, the linker uses \f(CW\*(C`_fini\*(C'\fR as +the function to call. +.IP \fB\-g\fR 4 +.IX Item "-g" +Ignored. Provided for compatibility with other tools. +.IP "\fB\-G\fR \fIvalue\fR" 4 +.IX Item "-G value" +.PD 0 +.IP \fB\-\-gpsize=\fR\fIvalue\fR 4 +.IX Item "--gpsize=value" +.PD +Set the maximum size of objects to be optimized using the GP register to +\&\fIsize\fR. This is only meaningful for object file formats such as +MIPS ELF that support putting large and small objects into different +sections. This is ignored for other object file formats. +.IP "\fB\-h\fR \fIname\fR" 4 +.IX Item "-h name" +.PD 0 +.IP \fB\-soname=\fR\fIname\fR 4 +.IX Item "-soname=name" +.PD +When creating an ELF shared object, set the internal DT_SONAME field to +the specified name. When an executable is linked with a shared object +which has a DT_SONAME field, then when the executable is run the dynamic +linker will attempt to load the shared object specified by the DT_SONAME +field rather than using the file name given to the linker. +.IP \fB\-i\fR 4 +.IX Item "-i" +Perform an incremental link (same as option \fB\-r\fR). +.IP \fB\-init=\fR\fIname\fR 4 +.IX Item "-init=name" +When creating an ELF executable or shared object, call NAME when the +executable or shared object is loaded, by setting DT_INIT to the address +of the function. By default, the linker uses \f(CW\*(C`_init\*(C'\fR as the +function to call. +.IP "\fB\-l\fR \fInamespec\fR" 4 +.IX Item "-l namespec" +.PD 0 +.IP \fB\-\-library=\fR\fInamespec\fR 4 +.IX Item "--library=namespec" +.PD +Add the archive or object file specified by \fInamespec\fR to the +list of files to link. This option may be used any number of times. +If \fInamespec\fR is of the form \fI:filename\fR, \fBld\fR +will search the library path for a file called \fIfilename\fR, otherwise it +will search the library path for a file called \fIlibnamespec.a\fR. +.Sp +On systems which support shared libraries, \fBld\fR may also search for +files other than \fIlibnamespec.a\fR. Specifically, on ELF +and SunOS systems, \fBld\fR will search a directory for a library +called \fIlibnamespec.so\fR before searching for one called +\&\fIlibnamespec.a\fR. (By convention, a \f(CW\*(C`.so\*(C'\fR extension +indicates a shared library.) Note that this behavior does not apply +to \fI:filename\fR, which always specifies a file called +\&\fIfilename\fR. +.Sp +The linker will search an archive only once, at the location where it is +specified on the command line. If the archive defines a symbol which +was undefined in some object which appeared before the archive on the +command line, the linker will include the appropriate file(s) from the +archive. However, an undefined symbol in an object appearing later on +the command line will not cause the linker to search the archive again. +.Sp +See the \fB\-(\fR option for a way to force the linker to search +archives multiple times. +.Sp +You may list the same archive multiple times on the command line. +.Sp +This type of archive searching is standard for Unix linkers. However, +if you are using \fBld\fR on AIX, note that it is different from the +behaviour of the AIX linker. +.IP "\fB\-L\fR \fIsearchdir\fR" 4 +.IX Item "-L searchdir" +.PD 0 +.IP \fB\-\-library\-path=\fR\fIsearchdir\fR 4 +.IX Item "--library-path=searchdir" +.PD +Add path \fIsearchdir\fR to the list of paths that \fBld\fR will search +for archive libraries and \fBld\fR control scripts. You may use this +option any number of times. The directories are searched in the order +in which they are specified on the command line. Directories specified +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. \fB\-L\fR options do not affect +how \fBld\fR searches for a linker script unless \fB\-T\fR +option is specified. +.Sp +If \fIsearchdir\fR begins with \f(CW\*(C`=\*(C'\fR or \f(CW$SYSROOT\fR, then this +prefix will be replaced by the \fIsysroot prefix\fR, controlled by the +\&\fB\-\-sysroot\fR option, or 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. +.Sp +The paths can also be specified in a link script with the +\&\f(CW\*(C`SEARCH_DIR\*(C'\fR command. Directories specified this way are searched +at the point in which the linker script appears in the command line. +.IP "\fB\-m\fR \fIemulation\fR" 4 +.IX Item "-m emulation" +Emulate the \fIemulation\fR linker. You can list the available +emulations with the \fB\-\-verbose\fR or \fB\-V\fR options. +.Sp +If the \fB\-m\fR option is not used, the emulation is taken from the +\&\f(CW\*(C`LDEMULATION\*(C'\fR environment variable, if that is defined. +.Sp +Otherwise, the default emulation depends upon how the linker was +configured. +.IP \fB\-\-remap\-inputs=\fR\f(BIpattern\fR\fB=\fR\f(BIfilename\fR 4 +.IX Item "--remap-inputs=pattern=filename" +.PD 0 +.IP \fB\-\-remap\-inputs\-file=\fR\f(BIfile\fR 4 +.IX Item "--remap-inputs-file=file" +.PD +These options allow the names of input files to be changed before the +linker attempts to open them. The option +\&\fB\-\-remap\-inputs=foo.o=bar.o\fR will cause any attempt to load a +file called \fIfoo.o\fR to instead try to load a file called +\&\fIbar.o\fR. Wildcard patterns are permitted in the first filename, +so \fB\-\-remap\-inputs=foo*.o=bar.o\fR will rename any input file that +matches \fIfoo*.o\fR to \fIbar.o\fR. +.Sp +An alternative form of the option +\&\fB\-\-remap\-inputs\-file=filename\fR allows the remappings to be read +from a file. Each line in the file can contain a single remapping. +Blank lines are ignored. Anything from a hash character (\fB#\fR) to +the end of a line is considered to be a comment and is also ignored. +The mapping pattern can be separated from the filename by whitespace +or an equals (\fB=\fR) character. +.Sp +The options can be specified multiple times. Their contents +accumulate. The remappings will be processed in the order in which +they occur on the command line, and if they come from a file, in the +order in which they occur in the file. If a match is made, no further +checking for that filename will be performed. +.Sp +If the replacement filename is \fI/dev/null\fR or just \fINUL\fR +then the remapping will actually cause the input file to be ignored. +This can be a convenient way to experiment with removing input files +from a complicated build environment. +.Sp +Note that this option is position dependent and only affects filenames +that come after it on the command line. Thus: +.Sp +.Vb 1 +\& ld foo.o \-\-remap\-inputs=foo.o=bar.o +.Ve +.Sp +Will have no effect, whereas: +.Sp +.Vb 1 +\& ld \-\-remap\-inputs=foo.o=bar.o foo.o +.Ve +.Sp +Will rename the input file \fIfoo.o\fR to \fIbar.o\fR. +.Sp +Note \- these options also affect files referenced by \fIINPUT\fR +statements in linker scripts. But since linker scripts are processed +after the entire command line is read, the position of the remap +options on the command line is not significant. +.Sp +If the \fBverbose\fR option is enabled then any mappings that match +will be reported, although again the \fBverbose\fR option needs to +be enabled on the command line \fIbefore\fR the remaped filenames +appear. +.Sp +If the \fB\-Map\fR or \fB\-\-print\-map\fR options are enabled then +the remapping list will be included in the map output. +.IP \fB\-M\fR 4 +.IX Item "-M" +.PD 0 +.IP \fB\-\-print\-map\fR 4 +.IX Item "--print-map" +.PD +Print a link map to the standard output. A link map provides +information about the link, including the following: +.RS 4 +.IP \(bu 4 +Where object files are mapped into memory. +.IP \(bu 4 +How common symbols are allocated. +.IP \(bu 4 +All archive members included in the link, with a mention of the symbol +which caused the archive member to be brought in. +.IP \(bu 4 +The values assigned to symbols. +.Sp +Note \- symbols whose values are computed by an expression which +involves a reference to a previous value of the same symbol may not +have correct result displayed in the link map. This is because the +linker discards intermediate results and only retains the final value +of an expression. Under such circumstances the linker will display +the final value enclosed by square brackets. Thus for example a +linker script containing: +.Sp +.Vb 3 +\& foo = 1 +\& foo = foo * 4 +\& foo = foo + 8 +.Ve +.Sp +will produce the following output in the link map if the \fB\-M\fR +option is used: +.Sp +.Vb 3 +\& 0x00000001 foo = 0x1 +\& [0x0000000c] foo = (foo * 0x4) +\& [0x0000000c] foo = (foo + 0x8) +.Ve +.Sp +See \fBExpressions\fR for more information about expressions in linker +scripts. +.IP \(bu 4 +How GNU properties are merged. +.Sp +When the linker merges input .note.gnu.property sections into one output +\&.note.gnu.property section, some properties are removed or updated. +These actions are reported in the link map. For example: +.Sp +.Vb 1 +\& Removed property 0xc0000002 to merge foo.o (0x1) and bar.o (not found) +.Ve +.Sp +This indicates that property 0xc0000002 is removed from output when +merging properties in \fIfoo.o\fR, whose property 0xc0000002 value +is 0x1, and \fIbar.o\fR, which doesn't have property 0xc0000002. +.Sp +.Vb 1 +\& Updated property 0xc0010001 (0x1) to merge foo.o (0x1) and bar.o (0x1) +.Ve +.Sp +This indicates that property 0xc0010001 value is updated to 0x1 in output +when merging properties in \fIfoo.o\fR, whose 0xc0010001 property value +is 0x1, and \fIbar.o\fR, whose 0xc0010001 property value is 0x1. +.RE +.RS 4 +.RE +.IP \fB\-\-print\-map\-discarded\fR 4 +.IX Item "--print-map-discarded" +.PD 0 +.IP \fB\-\-no\-print\-map\-discarded\fR 4 +.IX Item "--no-print-map-discarded" +.PD +Print (or do not print) the list of discarded and garbage collected sections +in the link map. Enabled by default. +.IP \fB\-\-print\-map\-locals\fR 4 +.IX Item "--print-map-locals" +.PD 0 +.IP \fB\-\-no\-print\-map\-locals\fR 4 +.IX Item "--no-print-map-locals" +.PD +Print (or do not print) local symbols in the link map. Local symbols +will have the text \fB(local)\fR printed before their name, and will +be listed after all of the global symbols in a given section. +Temporary local symbols (typically those that start with \fB.L\fR) +will not be included in the output. Disabled by default. +.IP \fB\-n\fR 4 +.IX Item "-n" +.PD 0 +.IP \fB\-\-nmagic\fR 4 +.IX Item "--nmagic" +.PD +Turn off page alignment of sections, and disable linking against shared +libraries. If the output format supports Unix style magic numbers, +mark the output as \f(CW\*(C`NMAGIC\*(C'\fR. +.IP \fB\-N\fR 4 +.IX Item "-N" +.PD 0 +.IP \fB\-\-omagic\fR 4 +.IX Item "--omagic" +.PD +Set the text and data sections to be readable and writable. Also, do +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 +.IP \fB\-\-output=\fR\fIoutput\fR 4 +.IX Item "--output=output" +.PD +Use \fIoutput\fR as the name for the program produced by \fBld\fR; if this +option is not specified, the name \fIa.out\fR is used by default. The +script command \f(CW\*(C`OUTPUT\*(C'\fR can also specify the output file name. +.IP \fB\-\-dependency\-file=\fR\fIdepfile\fR 4 +.IX Item "--dependency-file=depfile" +Write a \fIdependency file\fR to \fIdepfile\fR. This file contains a rule +suitable for \f(CW\*(C`make\*(C'\fR describing the output file and all the input files +that were read to produce it. The output is similar to the compiler's +output with \fB\-M \-MP\fR. Note that there is no option like the compiler's \fB\-MM\fR, +to exclude "system files" (which is not a well-specified concept in the +linker, unlike "system headers" in the compiler). So the output from +\&\fB\-\-dependency\-file\fR is always specific to the exact state of the +installation where it was produced, and should not be copied into +distributed makefiles without careful editing. +.IP "\fB\-O\fR \fIlevel\fR" 4 +.IX Item "-O level" +If \fIlevel\fR is a numeric values greater than zero \fBld\fR optimizes +the output. This might take significantly longer and therefore probably +should only be enabled for the final binary. At the moment this +option only affects ELF shared library generation. Future releases of +the linker may make more use of this option. Also currently there is +no difference in the linker's behaviour for different non-zero values +of this option. Again this may change with future releases. +.IP "\fB\-plugin\fR \fIname\fR" 4 +.IX Item "-plugin name" +Involve a plugin in the linking process. The \fIname\fR parameter is +the absolute filename of the plugin. Usually this parameter is +automatically added by the complier, when using link time +optimization, but users can also add their own plugins if they so +wish. +.Sp +Note that the location of the compiler originated plugins is different +from the place where the \fBar\fR, \fBnm\fR and +\&\fBranlib\fR programs search for their plugins. In order for +those commands to make use of a compiler based plugin it must first be +copied into the \fI${libdir}/bfd\-plugins\fR directory. All gcc +based linker plugins are backward compatible, so it is sufficient to +just copy in the newest one. +.IP \fB\-\-push\-state\fR 4 +.IX Item "--push-state" +The \fB\-\-push\-state\fR allows one to preserve the current state of the +flags which govern the input file handling so that they can all be +restored with one corresponding \fB\-\-pop\-state\fR option. +.Sp +The option which are covered are: \fB\-Bdynamic\fR, \fB\-Bstatic\fR, +\&\fB\-dn\fR, \fB\-dy\fR, \fB\-call_shared\fR, \fB\-non_shared\fR, +\&\fB\-static\fR, \fB\-N\fR, \fB\-n\fR, \fB\-\-whole\-archive\fR, +\&\fB\-\-no\-whole\-archive\fR, \fB\-r\fR, \fB\-Ur\fR, +\&\fB\-\-copy\-dt\-needed\-entries\fR, \fB\-\-no\-copy\-dt\-needed\-entries\fR, +\&\fB\-\-as\-needed\fR, \fB\-\-no\-as\-needed\fR, and \fB\-a\fR. +.Sp +One target for this option are specifications for \fIpkg-config\fR. When +used with the \fB\-\-libs\fR option all possibly needed libraries are +listed and then possibly linked with all the time. It is better to return +something as follows: +.Sp +.Vb 1 +\& \-Wl,\-\-push\-state,\-\-as\-needed \-libone \-libtwo \-Wl,\-\-pop\-state +.Ve +.IP \fB\-\-pop\-state\fR 4 +.IX Item "--pop-state" +Undoes the effect of \-\-push\-state, restores the previous values of the +flags governing input file handling. +.IP \fB\-q\fR 4 +.IX Item "-q" +.PD 0 +.IP \fB\-\-emit\-relocs\fR 4 +.IX Item "--emit-relocs" +.PD +Leave relocation sections and contents in fully linked executables. +Post link analysis and optimization tools may need this information in +order to perform correct modifications of executables. This results +in larger executables. +.Sp +This option is currently only supported on ELF platforms. +.IP \fB\-\-force\-dynamic\fR 4 +.IX Item "--force-dynamic" +Force the output file to have dynamic sections. This option is specific +to VxWorks targets. +.IP \fB\-r\fR 4 +.IX Item "-r" +.PD 0 +.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 +linking\fR. As a side effect, in environments that support standard Unix +magic numbers, this option also sets the output file's magic number to +\&\f(CW\*(C`OMAGIC\*(C'\fR. +If this option is not specified, an absolute file is produced. When +linking C++ programs, this option \fIwill not\fR resolve references to +constructors; to do that, use \fB\-Ur\fR. +.Sp +When an input file does not have the same format as the output file, +partial linking is only supported if that input file does not contain any +relocations. Different output formats can have further restrictions; for +example some \f(CW\*(C`a.out\*(C'\fR\-based formats do not support partial linking +with input files in other formats at all. +.Sp +This option does the same thing as \fB\-i\fR. +.IP "\fB\-R\fR \fIfilename\fR" 4 +.IX Item "-R filename" +.PD 0 +.IP \fB\-\-just\-symbols=\fR\fIfilename\fR 4 +.IX Item "--just-symbols=filename" +.PD +Read symbol names and their addresses from \fIfilename\fR, but do not +relocate it or include it in the output. This allows your output file +to refer symbolically to absolute locations of memory defined in other +programs. You may use this option more than once. +.Sp +For compatibility with other ELF linkers, if the \fB\-R\fR option is +followed by a directory name, rather than a file name, it is treated as +the \fB\-rpath\fR option. +.IP \fB\-s\fR 4 +.IX Item "-s" +.PD 0 +.IP \fB\-\-strip\-all\fR 4 +.IX Item "--strip-all" +.PD +Omit all symbol information from the output file. +.IP \fB\-S\fR 4 +.IX Item "-S" +.PD 0 +.IP \fB\-\-strip\-debug\fR 4 +.IX Item "--strip-debug" +.PD +Omit debugger symbol information (but not all symbols) from the output file. +.IP \fB\-\-strip\-discarded\fR 4 +.IX Item "--strip-discarded" +.PD 0 +.IP \fB\-\-no\-strip\-discarded\fR 4 +.IX Item "--no-strip-discarded" +.PD +Omit (or do not omit) global symbols defined in discarded sections. +Enabled by default. +.IP \fB\-t\fR 4 +.IX Item "-t" +.PD 0 +.IP \fB\-\-trace\fR 4 +.IX Item "--trace" +.PD +Print the names of the input files as \fBld\fR processes them. If +\&\fB\-t\fR is given twice then members within archives are also printed. +\&\fB\-t\fR output is useful to generate a list of all the object files +and scripts involved in linking, for example, when packaging files for +a linker bug report. +.IP "\fB\-T\fR \fIscriptfile\fR" 4 +.IX Item "-T scriptfile" +.PD 0 +.IP \fB\-\-script=\fR\fIscriptfile\fR 4 +.IX Item "--script=scriptfile" +.PD +Use \fIscriptfile\fR as the linker script. This script replaces +\&\fBld\fR's default linker script (rather than adding to it), +unless the script contains \f(CW\*(C`INSERT\*(C'\fR, so +\&\fIcommandfile\fR must specify everything necessary to describe the +output file. If \fIscriptfile\fR does not exist in +the current directory, \f(CW\*(C`ld\*(C'\fR looks for it in the directories +specified by any preceding \fB\-L\fR options. Multiple \fB\-T\fR +options accumulate. +.IP "\fB\-dT\fR \fIscriptfile\fR" 4 +.IX Item "-dT scriptfile" +.PD 0 +.IP \fB\-\-default\-script=\fR\fIscriptfile\fR 4 +.IX Item "--default-script=scriptfile" +.PD +Use \fIscriptfile\fR as the default linker script. +.Sp +This option is similar to the \fB\-\-script\fR option except that +processing of the script is delayed until after the rest of the +command line has been processed. This allows options placed after the +\&\fB\-\-default\-script\fR option on the command line to affect the +behaviour of the linker script, which can be important when the linker +command line cannot be directly controlled by the user. (eg because +the command line is being constructed by another tool, such as +\&\fBgcc\fR). +.IP "\fB\-u\fR \fIsymbol\fR" 4 +.IX Item "-u symbol" +.PD 0 +.IP \fB\-\-undefined=\fR\fIsymbol\fR 4 +.IX Item "--undefined=symbol" +.PD +Force \fIsymbol\fR to be entered in the output file as an undefined +symbol. Doing this may, for example, trigger linking of additional +modules from standard libraries. \fB\-u\fR may be repeated with +different option arguments to enter additional undefined symbols. This +option is equivalent to the \f(CW\*(C`EXTERN\*(C'\fR linker script command. +.Sp +If this option is being used to force additional modules to be pulled +into the link, and if it is an error for the symbol to remain +undefined, then the option \fB\-\-require\-defined\fR should be used +instead. +.IP \fB\-\-require\-defined=\fR\fIsymbol\fR 4 +.IX Item "--require-defined=symbol" +Require that \fIsymbol\fR is defined in the output file. This option +is the same as option \fB\-\-undefined\fR except that if \fIsymbol\fR +is not defined in the output file then the linker will issue an error +and exit. The same effect can be achieved in a linker script by using +\&\f(CW\*(C`EXTERN\*(C'\fR, \f(CW\*(C`ASSERT\*(C'\fR and \f(CW\*(C`DEFINED\*(C'\fR together. This option +can be used multiple times to require additional symbols. +.IP \fB\-Ur\fR 4 +.IX Item "-Ur" +For programs that do not use constructors or destructors, or for ELF +based systems this option is equivalent to \fB\-r\fR: it generates +relocatable output\-\-\-i.e., an output file that can in turn serve as +input to \fBld\fR. For other binaries however the \fB\-Ur\fR +option is similar to \fB\-r\fR but it also resolves references to +constructors and destructors. +.Sp +For those systems where \fB\-r\fR and \fB\-Ur\fR behave +differently, it does not work to use \fB\-Ur\fR on files that were +themselves linked with \fB\-Ur\fR; once the constructor table has +been built, it cannot be added to. Use \fB\-Ur\fR only for the last +partial link, and \fB\-r\fR for the others. +.IP \fB\-\-orphan\-handling=\fR\fIMODE\fR 4 +.IX Item "--orphan-handling=MODE" +Control how orphan sections are handled. An orphan section is one not +specifically mentioned in a linker script. +.Sp +\&\fIMODE\fR can have any of the following values: +.RS 4 +.ie n .IP """place""" 4 +.el .IP \f(CWplace\fR 4 +.IX Item "place" +Orphan sections are placed into a suitable output section following +the strategy described in \fBOrphan Sections\fR. The option +\&\fB\-\-unique\fR also affects how sections are placed. +.ie n .IP """discard""" 4 +.el .IP \f(CWdiscard\fR 4 +.IX Item "discard" +All orphan sections are discarded, by placing them in the +\&\fB/DISCARD/\fR section. +.ie n .IP """warn""" 4 +.el .IP \f(CWwarn\fR 4 +.IX Item "warn" +The linker will place the orphan section as for \f(CW\*(C`place\*(C'\fR and also +issue a warning. +.ie n .IP """error""" 4 +.el .IP \f(CWerror\fR 4 +.IX Item "error" +The linker will exit with an error if any orphan section is found. +.RE +.RS 4 +.Sp +The default if \fB\-\-orphan\-handling\fR is not given is \f(CW\*(C`place\*(C'\fR. +.RE +.IP \fB\-\-unique[=\fR\fISECTION\fR\fB]\fR 4 +.IX Item "--unique[=SECTION]" +Creates a separate output section for every input section matching +\&\fISECTION\fR, or if the optional wildcard \fISECTION\fR argument is +missing, for every orphan input section. An orphan section is one not +specifically mentioned in a linker script. You may use this option +multiple times on the command line; It prevents the normal merging of +input sections with the same name, overriding output section assignments +in a linker script. +.IP \fB\-v\fR 4 +.IX Item "-v" +.PD 0 +.IP \fB\-\-version\fR 4 +.IX Item "--version" +.IP \fB\-V\fR 4 +.IX Item "-V" +.PD +Display the version number for \fBld\fR. The \fB\-V\fR option also +lists the supported emulations. See also the description of the +\&\fB\-\-enable\-linker\-version\fR in \fBOptions,,Command\-line Options\fR +which can be used to insert the linker version string into a binary. +.IP \fB\-x\fR 4 +.IX Item "-x" +.PD 0 +.IP \fB\-\-discard\-all\fR 4 +.IX Item "--discard-all" +.PD +Delete all local symbols. +.IP \fB\-X\fR 4 +.IX Item "-X" +.PD 0 +.IP \fB\-\-discard\-locals\fR 4 +.IX Item "--discard-locals" +.PD +Delete all temporary local symbols. (These symbols start with +system-specific local label prefixes, typically \fB.L\fR for ELF systems +or \fBL\fR for traditional a.out systems.) +.IP "\fB\-y\fR \fIsymbol\fR" 4 +.IX Item "-y symbol" +.PD 0 +.IP \fB\-\-trace\-symbol=\fR\fIsymbol\fR 4 +.IX Item "--trace-symbol=symbol" +.PD +Print the name of each linked file in which \fIsymbol\fR appears. This +option may be given any number of times. On many systems it is necessary +to prepend an underscore. +.Sp +This option is useful when you have an undefined symbol in your link but +don't know where the reference is coming from. +.IP "\fB\-Y\fR \fIpath\fR" 4 +.IX Item "-Y path" +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: +.RS 4 +.IP \fBcall\-nop=prefix\-addr\fR 4 +.IX Item "call-nop=prefix-addr" +.PD 0 +.IP \fBcall\-nop=suffix\-nop\fR 4 +.IX Item "call-nop=suffix-nop" +.IP \fBcall\-nop=prefix\-\fR\fIbyte\fR 4 +.IX Item "call-nop=prefix-byte" +.IP \fBcall\-nop=suffix\-\fR\fIbyte\fR 4 +.IX Item "call-nop=suffix-byte" +.PD +Specify the 1\-byte \f(CW\*(C`NOP\*(C'\fR padding when transforming indirect call +to a locally defined function, foo, via its GOT slot. +\&\fBcall\-nop=prefix\-addr\fR generates \f(CW\*(C`0x67 call foo\*(C'\fR. +\&\fBcall\-nop=suffix\-nop\fR generates \f(CW\*(C`call foo 0x90\*(C'\fR. +\&\fBcall\-nop=prefix\-\fR\fIbyte\fR generates \f(CW\*(C`\fR\f(CIbyte\fR\f(CW call foo\*(C'\fR. +\&\fBcall\-nop=suffix\-\fR\fIbyte\fR generates \f(CW\*(C`call foo \fR\f(CIbyte\fR\f(CW\*(C'\fR. +Supported for i386 and x86_64. +.IP \fBcet\-report=none\fR 4 +.IX Item "cet-report=none" +.PD 0 +.IP \fBcet\-report=warning\fR 4 +.IX Item "cet-report=warning" +.IP \fBcet\-report=error\fR 4 +.IX Item "cet-report=error" +.PD +Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_IBT and +GNU_PROPERTY_X86_FEATURE_1_SHSTK properties in input .note.gnu.property +section. \fBcet\-report=none\fR, which is the default, will make the +linker not report missing properties in input files. +\&\fBcet\-report=warning\fR will make the linker issue a warning for +missing properties in input files. \fBcet\-report=error\fR will make +the linker issue an error for missing properties in input files. +Note that \fBibt\fR will turn off the missing +GNU_PROPERTY_X86_FEATURE_1_IBT property report and \fBshstk\fR will +turn off the missing GNU_PROPERTY_X86_FEATURE_1_SHSTK property report. +Supported for Linux/i386 and Linux/x86_64. +.IP \fBcombreloc\fR 4 +.IX Item "combreloc" +.PD 0 +.IP \fBnocombreloc\fR 4 +.IX Item "nocombreloc" +.PD +Combine multiple dynamic relocation sections and sort to improve +dynamic symbol lookup caching. Do not do this if \fBnocombreloc\fR. +.IP \fBcommon\fR 4 +.IX Item "common" +.PD 0 +.IP \fBnocommon\fR 4 +.IX Item "nocommon" +.PD +Generate common symbols with STT_COMMON type during a relocatable +link. Use STT_OBJECT type if \fBnocommon\fR. +.IP \fBcommon\-page\-size=\fR\fIvalue\fR 4 +.IX Item "common-page-size=value" +Set the page size most commonly used to \fIvalue\fR. Memory image +layout will be optimized to minimize memory pages if the system is +using pages of this size. +.IP \fBdefs\fR 4 +.IX Item "defs" +Report unresolved symbol references from regular object files. This +is done even if the linker is creating a non-symbolic shared library. +This option is the inverse of \fB\-z undefs\fR. +.IP \fBdynamic-undefined-weak\fR 4 +.IX Item "dynamic-undefined-weak" +.PD 0 +.IP \fBnodynamic-undefined-weak\fR 4 +.IX Item "nodynamic-undefined-weak" +.PD +Make undefined weak symbols dynamic when building a dynamic object, +if they are referenced from a regular object file and not forced local +by symbol visibility or versioning. Do not make them dynamic if +\&\fBnodynamic-undefined-weak\fR. If neither option is given, a target +may default to either option being in force, or make some other +selection of undefined weak symbols dynamic. Not all targets support +these options. +.IP \fBexecstack\fR 4 +.IX Item "execstack" +Marks the object as requiring executable stack. +.IP \fBglobal\fR 4 +.IX Item "global" +This option is only meaningful when building a shared object. It makes +the symbols defined by this shared object available for symbol resolution +of subsequently loaded libraries. +.IP \fBglobalaudit\fR 4 +.IX Item "globalaudit" +This option is only meaningful when building a dynamic executable. +This option marks the executable as requiring global auditing by +setting the \f(CW\*(C`DF_1_GLOBAUDIT\*(C'\fR bit in the \f(CW\*(C`DT_FLAGS_1\*(C'\fR dynamic +tag. Global auditing requires that any auditing library defined via +the \fB\-\-depaudit\fR or \fB\-P\fR command-line options be run for +all dynamic objects loaded by the application. +.IP \fBibtplt\fR 4 +.IX Item "ibtplt" +Generate Intel Indirect Branch Tracking (IBT) enabled PLT entries. +Supported for Linux/i386 and Linux/x86_64. +.IP \fBibt\fR 4 +.IX Item "ibt" +Generate GNU_PROPERTY_X86_FEATURE_1_IBT in .note.gnu.property section +to indicate compatibility with IBT. This also implies \fBibtplt\fR. +Supported for Linux/i386 and Linux/x86_64. +.IP \fBindirect-extern-access\fR 4 +.IX Item "indirect-extern-access" +.PD 0 +.IP \fBnoindirect-extern-access\fR 4 +.IX Item "noindirect-extern-access" +.PD +Generate GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS in +\&.note.gnu.property section to indicate that object file requires +canonical function pointers and cannot be used with copy relocation. +This option also implies \fBnoextern-protected-data\fR and +\&\fBnocopyreloc\fR. Supported for i386 and x86\-64. +.Sp +\&\fBnoindirect-extern-access\fR removes +GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS from .note.gnu.property +section. +.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" +Specify that the dynamic loader should modify its symbol search order +so that symbols in this shared library interpose all other shared +libraries not so marked. +.IP \fBunique\fR 4 +.IX Item "unique" +.PD 0 +.IP \fBnounique\fR 4 +.IX Item "nounique" +.PD +When generating a shared library or other dynamically loadable ELF +object mark it as one that should (by default) only ever be loaded once, +and only in the main namespace (when using \f(CW\*(C`dlmopen\*(C'\fR). This is +primarily used to mark fundamental libraries such as libc, libpthread et +al which do not usually function correctly unless they are the sole instances +of themselves. This behaviour can be overridden by the \f(CW\*(C`dlmopen\*(C'\fR caller +and does not apply to certain loading mechanisms (such as audit libraries). +.IP \fBlam\-u48\fR 4 +.IX Item "lam-u48" +Generate GNU_PROPERTY_X86_FEATURE_1_LAM_U48 in .note.gnu.property section +to indicate compatibility with Intel LAM_U48. Supported for Linux/x86_64. +.IP \fBlam\-u57\fR 4 +.IX Item "lam-u57" +Generate GNU_PROPERTY_X86_FEATURE_1_LAM_U57 in .note.gnu.property section +to indicate compatibility with Intel LAM_U57. Supported for Linux/x86_64. +.IP \fBlam\-u48\-report=none\fR 4 +.IX Item "lam-u48-report=none" +.PD 0 +.IP \fBlam\-u48\-report=warning\fR 4 +.IX Item "lam-u48-report=warning" +.IP \fBlam\-u48\-report=error\fR 4 +.IX Item "lam-u48-report=error" +.PD +Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U48 +property in input .note.gnu.property section. +\&\fBlam\-u48\-report=none\fR, which is the default, will make the +linker not report missing properties in input files. +\&\fBlam\-u48\-report=warning\fR will make the linker issue a warning for +missing properties in input files. \fBlam\-u48\-report=error\fR will +make the linker issue an error for missing properties in input files. +Supported for Linux/x86_64. +.IP \fBlam\-u57\-report=none\fR 4 +.IX Item "lam-u57-report=none" +.PD 0 +.IP \fBlam\-u57\-report=warning\fR 4 +.IX Item "lam-u57-report=warning" +.IP \fBlam\-u57\-report=error\fR 4 +.IX Item "lam-u57-report=error" +.PD +Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U57 +property in input .note.gnu.property section. +\&\fBlam\-u57\-report=none\fR, which is the default, will make the +linker not report missing properties in input files. +\&\fBlam\-u57\-report=warning\fR will make the linker issue a warning for +missing properties in input files. \fBlam\-u57\-report=error\fR will +make the linker issue an error for missing properties in input files. +Supported for Linux/x86_64. +.IP \fBlam\-report=none\fR 4 +.IX Item "lam-report=none" +.PD 0 +.IP \fBlam\-report=warning\fR 4 +.IX Item "lam-report=warning" +.IP \fBlam\-report=error\fR 4 +.IX Item "lam-report=error" +.PD +Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U48 and +GNU_PROPERTY_X86_FEATURE_1_LAM_U57 properties in input .note.gnu.property +section. \fBlam\-report=none\fR, which is the default, will make the +linker not report missing properties in input files. +\&\fBlam\-report=warning\fR will make the linker issue a warning for +missing properties in input files. \fBlam\-report=error\fR will make +the linker issue an error for missing properties in input files. +Supported for Linux/x86_64. +.IP \fBlazy\fR 4 +.IX Item "lazy" +When generating an executable or shared library, mark it to tell the +dynamic linker to defer function call resolution to the point when +the function is called (lazy binding), rather than at load time. +Lazy binding is the default. +.IP \fBloadfltr\fR 4 +.IX Item "loadfltr" +Specify that the object's filters be processed immediately at runtime. +.IP \fBmax\-page\-size=\fR\fIvalue\fR 4 +.IX Item "max-page-size=value" +Set the maximum memory page size supported to \fIvalue\fR. +.IP \fBmuldefs\fR 4 +.IX Item "muldefs" +Allow multiple definitions. +.IP \fBnocopyreloc\fR 4 +.IX Item "nocopyreloc" +Disable linker generated .dynbss variables used in place of variables +defined in shared libraries. May result in dynamic text relocations. +.IP \fBnodefaultlib\fR 4 +.IX Item "nodefaultlib" +Specify that the dynamic loader search for dependencies of this object +should ignore any default library search paths. +.IP \fBnodelete\fR 4 +.IX Item "nodelete" +Specify that the object shouldn't be unloaded at runtime. +.IP \fBnodlopen\fR 4 +.IX Item "nodlopen" +Specify that the object is not available to \f(CW\*(C`dlopen\*(C'\fR. +.IP \fBnodump\fR 4 +.IX Item "nodump" +Specify that the object can not be dumped by \f(CW\*(C`dldump\*(C'\fR. +.IP \fBnoexecstack\fR 4 +.IX Item "noexecstack" +Marks the object as not requiring executable stack. +.IP \fBnoextern-protected-data\fR 4 +.IX Item "noextern-protected-data" +Don't treat protected data symbols as external when building a shared +library. This option overrides the linker backend default. It can be +used to work around incorrect relocations against protected data symbols +generated by compiler. Updates on protected data symbols by another +module aren't visible to the resulting shared library. Supported for +i386 and x86\-64. +.IP \fBnoreloc-overflow\fR 4 +.IX Item "noreloc-overflow" +Disable relocation overflow check. This can be used to disable +relocation overflow check if there will be no dynamic relocation +overflow at run-time. Supported for x86_64. +.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 loaded by dlopen, instead of deferring +function call resolution to the point when the function is first +called. +.IP \fBorigin\fR 4 +.IX Item "origin" +Specify that the object requires \fR\f(CB$ORIGIN\fR\fB\fR handling in paths. +.IP \fBpack-relative-relocs\fR 4 +.IX Item "pack-relative-relocs" +.PD 0 +.IP \fBnopack-relative-relocs\fR 4 +.IX Item "nopack-relative-relocs" +.PD +Generate compact relative relocation in position-independent executable +and shared library. It adds \f(CW\*(C`DT_RELR\*(C'\fR, \f(CW\*(C`DT_RELRSZ\*(C'\fR and +\&\f(CW\*(C`DT_RELRENT\*(C'\fR entries to the dynamic section. It is ignored when +building position-dependent executable and relocatable output. +\&\fBnopack-relative-relocs\fR is the default, which disables compact +relative relocation. When linked against the GNU C Library, a +GLIBC_ABI_DT_RELR symbol version dependency on the shared C Library is +added to the output. Supported for i386 and x86\-64. +.IP \fBrelro\fR 4 +.IX Item "relro" +.PD 0 +.IP \fBnorelro\fR 4 +.IX Item "norelro" +.PD +Create an ELF \f(CW\*(C`PT_GNU_RELRO\*(C'\fR segment header in the object. This +specifies a memory segment that should be made read-only after +relocation, if supported. Specifying \fBcommon-page-size\fR smaller +than the system page size will render this protection ineffective. +Don't create an ELF \f(CW\*(C`PT_GNU_RELRO\*(C'\fR segment if \fBnorelro\fR. +.IP \fBreport-relative-reloc\fR 4 +.IX Item "report-relative-reloc" +Report dynamic relative relocations generated by linker. Supported for +Linux/i386 and Linux/x86_64. +.IP \fBsectionheader\fR 4 +.IX Item "sectionheader" +.PD 0 +.IP \fBnosectionheader\fR 4 +.IX Item "nosectionheader" +.PD +Generate section header. Don't generate section header if +\&\fBnosectionheader\fR is used. \fBsectionheader\fR is the default. +.IP \fBseparate-code\fR 4 +.IX Item "separate-code" +.PD 0 +.IP \fBnoseparate-code\fR 4 +.IX Item "noseparate-code" +.PD +Create separate code \f(CW\*(C`PT_LOAD\*(C'\fR segment header in the object. This +specifies a memory segment that should contain only instructions and must +be in wholly disjoint pages from any other data. Don't create separate +code \f(CW\*(C`PT_LOAD\*(C'\fR segment if \fBnoseparate-code\fR is used. +.IP \fBshstk\fR 4 +.IX Item "shstk" +Generate GNU_PROPERTY_X86_FEATURE_1_SHSTK in .note.gnu.property section +to indicate compatibility with Intel Shadow Stack. Supported for +Linux/i386 and Linux/x86_64. +.IP \fBstack\-size=\fR\fIvalue\fR 4 +.IX Item "stack-size=value" +Specify a stack size for an ELF \f(CW\*(C`PT_GNU_STACK\*(C'\fR segment. +Specifying zero will override any default non-zero sized +\&\f(CW\*(C`PT_GNU_STACK\*(C'\fR segment creation. +.IP \fBstart-stop-gc\fR 4 +.IX Item "start-stop-gc" +.PD 0 +.IP \fBnostart-stop-gc\fR 4 +.IX Item "nostart-stop-gc" +.PD +When \fB\-\-gc\-sections\fR is in effect, a reference from a retained +section to \f(CW\*(C`_\|_start_SECNAME\*(C'\fR or \f(CW\*(C`_\|_stop_SECNAME\*(C'\fR causes all +input sections named \f(CW\*(C`SECNAME\*(C'\fR to also be retained, if +\&\f(CW\*(C`SECNAME\*(C'\fR is representable as a C identifier and either +\&\f(CW\*(C`_\|_start_SECNAME\*(C'\fR or \f(CW\*(C`_\|_stop_SECNAME\*(C'\fR is synthesized by the +linker. \fB\-z start-stop-gc\fR disables this effect, allowing +sections to be garbage collected as if the special synthesized symbols +were not defined. \fB\-z start-stop-gc\fR has no effect on a +definition of \f(CW\*(C`_\|_start_SECNAME\*(C'\fR or \f(CW\*(C`_\|_stop_SECNAME\*(C'\fR in an +object file or linker script. Such a definition will prevent the +linker providing a synthesized \f(CW\*(C`_\|_start_SECNAME\*(C'\fR or +\&\f(CW\*(C`_\|_stop_SECNAME\*(C'\fR respectively, and therefore the special +treatment by garbage collection for those references. +.IP \fBstart\-stop\-visibility=\fR\fIvalue\fR 4 +.IX Item "start-stop-visibility=value" +Specify the ELF symbol visibility for synthesized +\&\f(CW\*(C`_\|_start_SECNAME\*(C'\fR and \f(CW\*(C`_\|_stop_SECNAME\*(C'\fR symbols. \fIvalue\fR must be exactly \fBdefault\fR, +\&\fBinternal\fR, \fBhidden\fR, or \fBprotected\fR. If no \fB\-z +start-stop-visibility\fR option is given, \fBprotected\fR is used for +compatibility with historical practice. However, it's highly +recommended to use \fB\-z start\-stop\-visibility=hidden\fR in new +programs and shared libraries so that these symbols are not exported +between shared objects, which is not usually what's intended. +.IP \fBtext\fR 4 +.IX Item "text" +.PD 0 +.IP \fBnotext\fR 4 +.IX Item "notext" +.IP \fBtextoff\fR 4 +.IX Item "textoff" +.PD +Report an error if DT_TEXTREL is set, i.e., if the position-independent +or shared object has dynamic relocations in read-only sections. Don't +report an error if \fBnotext\fR or \fBtextoff\fR. +.IP \fBundefs\fR 4 +.IX Item "undefs" +Do not report unresolved symbol references from regular object files, +either when creating an executable, or when creating a shared library. +This option is the inverse of \fB\-z defs\fR. +.IP \fBunique-symbol\fR 4 +.IX Item "unique-symbol" +.PD 0 +.IP \fBnounique-symbol\fR 4 +.IX Item "nounique-symbol" +.PD +Avoid duplicated local symbol names in the symbol string table. Append +".\f(CW\*(C`number\*(C'\fR" to duplicated local symbol names if \fBunique-symbol\fR +is used. \fBnounique-symbol\fR is the default. +.IP \fBx86\-64\-baseline\fR 4 +.IX Item "x86-64-baseline" +.PD 0 +.IP \fBx86\-64\-v2\fR 4 +.IX Item "x86-64-v2" +.IP \fBx86\-64\-v3\fR 4 +.IX Item "x86-64-v3" +.IP \fBx86\-64\-v4\fR 4 +.IX Item "x86-64-v4" +.PD +Specify the x86\-64 ISA level needed in .note.gnu.property section. +\&\fBx86\-64\-baseline\fR generates \f(CW\*(C`GNU_PROPERTY_X86_ISA_1_BASELINE\*(C'\fR. +\&\fBx86\-64\-v2\fR generates \f(CW\*(C`GNU_PROPERTY_X86_ISA_1_V2\*(C'\fR. +\&\fBx86\-64\-v3\fR generates \f(CW\*(C`GNU_PROPERTY_X86_ISA_1_V3\*(C'\fR. +\&\fBx86\-64\-v4\fR generates \f(CW\*(C`GNU_PROPERTY_X86_ISA_1_V4\*(C'\fR. +Supported for Linux/i386 and Linux/x86_64. +.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 +.IP "\fB\-\-start\-group\fR \fIarchives\fR \fB\-\-end\-group\fR" 4 +.IX Item "--start-group archives --end-group" +.PD +The \fIarchives\fR should be a list of archive files. They may be +either explicit file names, or \fB\-l\fR options. +.Sp +The specified archives are searched repeatedly until no new undefined +references are created. Normally, an archive is searched only once in +the order that it is specified on the command line. If a symbol in that +archive is needed to resolve an undefined symbol referred to by an +object in an archive that appears later on the command line, the linker +would not be able to resolve that reference. By grouping the archives, +they will all be searched repeatedly until all possible references are +resolved. +.Sp +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 ELF DT_NEEDED tags for dynamic libraries mentioned +on the command line after the \fB\-\-as\-needed\fR option. Normally +the linker will add a DT_NEEDED tag for each dynamic library mentioned +on the command line, regardless of whether the library is actually +needed or not. \fB\-\-as\-needed\fR causes a DT_NEEDED tag to only be +emitted for a library that \fIat that point in the link\fR satisfies a +non-weak undefined symbol reference from a regular object file or, if +the library is not found in the DT_NEEDED lists of other needed libraries, a +non-weak undefined symbol reference from another needed dynamic library. +Object files or libraries appearing on the command line \fIafter\fR +the library in question do not affect whether the library is seen as +needed. This is similar to the rules for extraction of object files +from archives. \fB\-\-no\-as\-needed\fR restores the default behaviour. +.Sp +Note: On Linux based systems the \fB\-\-as\-needed\fR option also has +an affect on the behaviour of the \fB\-\-rpath\fR and +\&\fB\-\-rpath\-link\fR options. See the description of +\&\fB\-\-rpath\-link\fR for more details. +.IP \fB\-\-add\-needed\fR 4 +.IX Item "--add-needed" +.PD 0 +.IP \fB\-\-no\-add\-needed\fR 4 +.IX Item "--no-add-needed" +.PD +These two options have been deprecated because of the similarity of +their names to the \fB\-\-as\-needed\fR and \fB\-\-no\-as\-needed\fR +options. They have been replaced by \fB\-\-copy\-dt\-needed\-entries\fR +and \fB\-\-no\-copy\-dt\-needed\-entries\fR. +.IP "\fB\-assert\fR \fIkeyword\fR" 4 +.IX Item "-assert keyword" +This option is ignored for SunOS compatibility. +.IP \fB\-Bdynamic\fR 4 +.IX Item "-Bdynamic" +.PD 0 +.IP \fB\-dy\fR 4 +.IX Item "-dy" +.IP \fB\-call_shared\fR 4 +.IX Item "-call_shared" +.PD +Link against dynamic libraries. This is only meaningful on platforms +for which shared libraries are supported. This option is normally the +default on such platforms. 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. +.IP \fB\-Bgroup\fR 4 +.IX Item "-Bgroup" +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\-\-unresolved\-symbols=report\-all\fR is implied. This option is +only meaningful on ELF platforms which support shared libraries. +.IP \fB\-Bstatic\fR 4 +.IX Item "-Bstatic" +.PD 0 +.IP \fB\-dn\fR 4 +.IX Item "-dn" +.IP \fB\-non_shared\fR 4 +.IX Item "-non_shared" +.IP \fB\-static\fR 4 +.IX Item "-static" +.PD +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. This +option also implies \fB\-\-unresolved\-symbols=report\-all\fR. This +option can be used with \fB\-shared\fR. Doing so means that a +shared library is being created but that all of the library's external +references must be resolved by pulling in entries from static +libraries. +.IP \fB\-Bsymbolic\fR 4 +.IX Item "-Bsymbolic" +When creating a shared library, bind references to global symbols to the +definition within the shared library, if any. Normally, it is possible +for a program linked against a shared library to override the definition +within the shared library. This option is only meaningful on ELF +platforms which support shared libraries. +.IP \fB\-Bsymbolic\-functions\fR 4 +.IX Item "-Bsymbolic-functions" +When creating a shared library, bind references to global function +symbols to the definition within the shared library, if any. +This option is only meaningful on ELF platforms which support shared +libraries. +.IP \fB\-Bno\-symbolic\fR 4 +.IX Item "-Bno-symbolic" +This option can cancel previously specified \fB\-Bsymbolic\fR and +\&\fB\-Bsymbolic\-functions\fR. +.IP \fB\-\-dynamic\-list=\fR\fIdynamic-list-file\fR 4 +.IX Item "--dynamic-list=dynamic-list-file" +Specify the name of a dynamic list file to the linker. This is +typically used when creating shared libraries to specify a list of +global symbols whose references shouldn't be bound to the definition +within the shared library, or creating dynamically linked executables +to specify a list of symbols which should be added to the symbol table +in the executable. This option is only meaningful on ELF platforms +which support shared libraries. +.Sp +The format of the dynamic list is the same as the version node without +scope and node name. See \fBVERSION\fR for more information. +.IP \fB\-\-dynamic\-list\-data\fR 4 +.IX Item "--dynamic-list-data" +Include all global data symbols to the dynamic list. +.IP \fB\-\-dynamic\-list\-cpp\-new\fR 4 +.IX Item "--dynamic-list-cpp-new" +Provide the builtin dynamic list for C++ operator new and delete. It +is mainly useful for building shared libstdc++. +.IP \fB\-\-dynamic\-list\-cpp\-typeinfo\fR 4 +.IX Item "--dynamic-list-cpp-typeinfo" +Provide the builtin dynamic list for C++ runtime type identification. +.IP \fB\-\-check\-sections\fR 4 +.IX Item "--check-sections" +.PD 0 +.IP \fB\-\-no\-check\-sections\fR 4 +.IX Item "--no-check-sections" +.PD +Asks the linker \fInot\fR to check section addresses after they have +been assigned to see if there are any overlaps. Normally the linker will +perform this check, and if it finds any overlaps it will produce +suitable error messages. The linker does know about, and does make +allowances for sections in overlays. The default behaviour can be +restored by using the command-line switch \fB\-\-check\-sections\fR. +Section overlap is not usually checked for relocatable links. You can +force checking in that case by using the \fB\-\-check\-sections\fR +option. +.IP \fB\-\-copy\-dt\-needed\-entries\fR 4 +.IX Item "--copy-dt-needed-entries" +.PD 0 +.IP \fB\-\-no\-copy\-dt\-needed\-entries\fR 4 +.IX Item "--no-copy-dt-needed-entries" +.PD +This option affects the treatment of dynamic libraries referred to +by DT_NEEDED tags \fIinside\fR ELF dynamic libraries mentioned on the +command line. Normally the linker won't add a DT_NEEDED tag to the +output binary for each library mentioned in a DT_NEEDED tag in an +input dynamic library. With \fB\-\-copy\-dt\-needed\-entries\fR +specified on the command line however any dynamic libraries that +follow it will have their DT_NEEDED entries added. The default +behaviour can be restored with \fB\-\-no\-copy\-dt\-needed\-entries\fR. +.Sp +This option also has an effect on the resolution of symbols in dynamic +libraries. With \fB\-\-copy\-dt\-needed\-entries\fR dynamic libraries +mentioned on the command line will be recursively searched, following +their DT_NEEDED tags to other libraries, in order to resolve symbols +required by the output binary. With the default setting however +the searching of dynamic libraries that follow it will stop with the +dynamic library itself. No DT_NEEDED links will be traversed to resolve +symbols. +.IP \fB\-\-cref\fR 4 +.IX Item "--cref" +Output a cross reference table. If a linker map file is being +generated, the cross reference table is printed to the map file. +Otherwise, it is printed on the standard output. +.Sp +The format of the table is intentionally simple, so that it may be +easily processed by a script if necessary. The symbols are printed out, +sorted by name. For each symbol, a list of file names is given. If the +symbol is defined, the first file listed is the location of the +definition. If the symbol is defined as a common value then any files +where this happens appear next. Finally any files that reference the +symbol are listed. +.IP \fB\-\-ctf\-variables\fR 4 +.IX Item "--ctf-variables" +.PD 0 +.IP \fB\-\-no\-ctf\-variables\fR 4 +.IX Item "--no-ctf-variables" +.PD +The CTF debuginfo format supports a section which encodes the names and +types of variables found in the program which do not appear in any symbol +table. These variables clearly cannot be looked up by address by +conventional debuggers, so the space used for their types and names is +usually wasted: the types are usually small but the names are often not. +\&\fB\-\-ctf\-variables\fR causes the generation of such a section. +The default behaviour can be restored with \fB\-\-no\-ctf\-variables\fR. +.IP \fB\-\-ctf\-share\-types=\fR\fImethod\fR 4 +.IX Item "--ctf-share-types=method" +Adjust the method used to share types between translation units in CTF. +.RS 4 +.IP \fBshare-unconflicted\fR 4 +.IX Item "share-unconflicted" +Put all types that do not have ambiguous definitions into the shared dictionary, +where debuggers can easily access them, even if they only occur in one +translation unit. This is the default. +.IP \fBshare-duplicated\fR 4 +.IX Item "share-duplicated" +Put only types that occur in multiple translation units into the shared +dictionary: types with only one definition go into per-translation-unit +dictionaries. Types with ambiguous definitions in multiple translation units +always go into per-translation-unit dictionaries. This tends to make the CTF +larger, but may reduce the amount of CTF in the shared dictionary. For very +large projects this may speed up opening the CTF and save memory in the CTF +consumer at runtime. +.RE +.RS 4 +.RE +.IP \fB\-\-no\-define\-common\fR 4 +.IX Item "--no-define-common" +This option inhibits the assignment of addresses to common symbols. +The script command \f(CW\*(C`INHIBIT_COMMON_ALLOCATION\*(C'\fR has the same effect. +.Sp +The \fB\-\-no\-define\-common\fR option allows decoupling +the decision to assign addresses to Common symbols from the choice +of the output file type; otherwise a non-Relocatable output type +forces assigning addresses to Common symbols. +Using \fB\-\-no\-define\-common\fR allows Common symbols that are referenced +from a shared library to be assigned addresses only in the main program. +This eliminates the unused duplicate space in the shared library, +and also prevents any possible confusion over resolving to the wrong +duplicate when there are many dynamic modules with specialized search +paths for runtime symbol resolution. +.IP \fB\-\-force\-group\-allocation\fR 4 +.IX Item "--force-group-allocation" +This option causes the linker to place section group members like +normal input sections, and to delete the section groups. This is the +default behaviour for a final link but this option can be used to +change the behaviour of a relocatable link (\fB\-r\fR). The script +command \f(CW\*(C`FORCE_GROUP_ALLOCATION\*(C'\fR has the same +effect. +.IP \fB\-\-defsym=\fR\fIsymbol\fR\fB=\fR\fIexpression\fR 4 +.IX Item "--defsym=symbol=expression" +Create a global symbol in the output file, containing the absolute +address given by \fIexpression\fR. You may use this option as many +times as necessary to define multiple symbols in the command line. A +limited form of arithmetic is supported for the \fIexpression\fR in this +context: you may give a hexadecimal constant or the name of an existing +symbol, or use \f(CW\*(C`+\*(C'\fR and \f(CW\*(C`\-\*(C'\fR to add or subtract hexadecimal +constants or symbols. If you need more elaborate expressions, consider +using the linker command language from a script. +\&\fINote:\fR there should be no white space between \fIsymbol\fR, the +equals sign ("\fB=\fR"), and \fIexpression\fR. +.Sp +The linker processes \fB\-\-defsym\fR arguments and \fB\-T\fR arguments +in order, placing \fB\-\-defsym\fR before \fB\-T\fR will define the +symbol before the linker script from \fB\-T\fR is processed, while +placing \fB\-\-defsym\fR after \fB\-T\fR will define the symbol after +the linker script has been processed. This difference has +consequences for expressions within the linker script that use the +\&\fB\-\-defsym\fR symbols, which order is correct will depend on what +you are trying to achieve. +.IP \fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR 4 +.IX Item "--demangle[=style]" +.PD 0 +.IP \fB\-\-no\-demangle\fR 4 +.IX Item "--no-demangle" +.PD +These options control whether to demangle symbol names in error messages +and other output. When the linker is told to demangle, it tries to +present symbol names in a readable fashion: it strips leading +underscores if they are used by the object file format, and converts C++ +mangled symbol names into user readable names. Different compilers have +different mangling styles. The optional demangling style argument can be used +to choose an appropriate demangling style for your compiler. The linker will +demangle by default unless the environment variable \fBCOLLECT_NO_DEMANGLE\fR +is set. These options may be used to override the default. +.IP \fB\-I\fR\fIfile\fR 4 +.IX Item "-Ifile" +.PD 0 +.IP \fB\-\-dynamic\-linker=\fR\fIfile\fR 4 +.IX Item "--dynamic-linker=file" +.PD +Set the name of the dynamic linker. This is only meaningful when +generating dynamically linked ELF executables. The default dynamic +linker is normally correct; don't use this unless you know what you are +doing. +.IP \fB\-\-no\-dynamic\-linker\fR 4 +.IX Item "--no-dynamic-linker" +When producing an executable file, omit the request for a dynamic +linker to be used at load-time. This is only meaningful for ELF +executables that contain dynamic relocations, and usually requires +entry point code that is capable of processing these relocations. +.IP \fB\-\-embedded\-relocs\fR 4 +.IX Item "--embedded-relocs" +This option is similar to the \fB\-\-emit\-relocs\fR option except +that the relocs are stored in a target-specific section. This option +is only supported by the \fBBFIN\fR, \fBCR16\fR and \fIM68K\fR +targets. +.IP \fB\-\-disable\-multiple\-abs\-defs\fR 4 +.IX Item "--disable-multiple-abs-defs" +Do not allow multiple definitions with symbols included +in filename invoked by \-R or \-\-just\-symbols +.IP \fB\-\-fatal\-warnings\fR 4 +.IX Item "--fatal-warnings" +.PD 0 +.IP \fB\-\-no\-fatal\-warnings\fR 4 +.IX Item "--no-fatal-warnings" +.PD +Treat all warnings as errors. The default behaviour can be restored +with the option \fB\-\-no\-fatal\-warnings\fR. +.IP \fB\-w\fR 4 +.IX Item "-w" +.PD 0 +.IP \fB\-\-no\-warnings\fR 4 +.IX Item "--no-warnings" +.PD +Do not display any warning or error messages. This overrides +\&\fB\-\-fatal\-warnings\fR if it has been enabled. This option can be +used when it is known that the output binary will not work, but there +is still a need to create it. +.IP \fB\-\-force\-exe\-suffix\fR 4 +.IX Item "--force-exe-suffix" +Make sure that an output file has a .exe suffix. +.Sp +If a successfully built fully linked output file does not have a +\&\f(CW\*(C`.exe\*(C'\fR or \f(CW\*(C`.dll\*(C'\fR suffix, this option forces the linker to copy +the output file to one of the same name with a \f(CW\*(C`.exe\*(C'\fR suffix. This +option is useful when using unmodified Unix makefiles on a Microsoft +Windows host, since some versions of Windows won't run an image unless +it ends in a \f(CW\*(C`.exe\*(C'\fR suffix. +.IP \fB\-\-gc\-sections\fR 4 +.IX Item "--gc-sections" +.PD 0 +.IP \fB\-\-no\-gc\-sections\fR 4 +.IX Item "--no-gc-sections" +.PD +Enable garbage collection of unused input sections. It is ignored on +targets that do not support this option. The default behaviour (of not +performing this garbage collection) can be restored by specifying +\&\fB\-\-no\-gc\-sections\fR on the command line. Note that garbage +collection for COFF and PE format targets is supported, but the +implementation is currently considered to be experimental. +.Sp +\&\fB\-\-gc\-sections\fR decides which input sections are used by +examining symbols and relocations. The section containing the entry +symbol and all sections containing symbols undefined on the +command-line will be kept, as will sections containing symbols +referenced by dynamic objects. Note that when building shared +libraries, the linker must assume that any visible symbol is +referenced. Once this initial set of sections has been determined, +the linker recursively marks as used any section referenced by their +relocations. See \fB\-\-entry\fR, \fB\-\-undefined\fR, and +\&\fB\-\-gc\-keep\-exported\fR. +.Sp +This option can be set when doing a partial link (enabled with option +\&\fB\-r\fR). In this case the root of symbols kept must be explicitly +specified either by one of the options \fB\-\-entry\fR, +\&\fB\-\-undefined\fR, or \fB\-\-gc\-keep\-exported\fR or by a \f(CW\*(C`ENTRY\*(C'\fR +command in the linker script. +.Sp +As a GNU extension, ELF input sections marked with the +\&\f(CW\*(C`SHF_GNU_RETAIN\*(C'\fR flag will not be garbage collected. +.IP \fB\-\-print\-gc\-sections\fR 4 +.IX Item "--print-gc-sections" +.PD 0 +.IP \fB\-\-no\-print\-gc\-sections\fR 4 +.IX Item "--no-print-gc-sections" +.PD +List all sections removed by garbage collection. The listing is +printed on stderr. This option is only effective if garbage +collection has been enabled via the \fB\-\-gc\-sections\fR) option. The +default behaviour (of not listing the sections that are removed) can +be restored by specifying \fB\-\-no\-print\-gc\-sections\fR on the command +line. +.IP \fB\-\-gc\-keep\-exported\fR 4 +.IX Item "--gc-keep-exported" +When \fB\-\-gc\-sections\fR is enabled, this option prevents garbage +collection of unused input sections that contain global symbols having +default or protected visibility. This option is intended to be used for +executables where unreferenced sections would otherwise be garbage +collected regardless of the external visibility of contained symbols. +Note that this option has no effect when linking shared objects since +it is already the default behaviour. This option is only supported for +ELF format targets. +.IP \fB\-\-print\-output\-format\fR 4 +.IX Item "--print-output-format" +Print the name of the default output format (perhaps influenced by +other command-line options). This is the string that would appear +in an \f(CW\*(C`OUTPUT_FORMAT\*(C'\fR linker script command. +.IP \fB\-\-print\-memory\-usage\fR 4 +.IX Item "--print-memory-usage" +Print used size, total size and used size of memory regions created with +the \fBMEMORY\fR command. This is useful on embedded targets to have a +quick view of amount of free memory. The format of the output has one +headline and one line per region. It is both human readable and easily +parsable by tools. Here is an example of an output: +.Sp +.Vb 3 +\& Memory region Used Size Region Size %age Used +\& ROM: 256 KB 1 MB 25.00% +\& RAM: 32 B 2 GB 0.00% +.Ve +.IP \fB\-\-help\fR 4 +.IX Item "--help" +Print a summary of the command-line options on the standard output and exit. +.IP \fB\-\-target\-help\fR 4 +.IX Item "--target-help" +Print a summary of all target-specific options on the standard output and exit. +.IP \fB\-Map=\fR\fImapfile\fR 4 +.IX Item "-Map=mapfile" +Print a link map to the file \fImapfile\fR. See the description of the +\&\fB\-M\fR option, above. If \fImapfile\fR is just the character +\&\f(CW\*(C`\-\*(C'\fR then the map will be written to stdout. +.Sp +Specifying a directory as \fImapfile\fR causes the linker map to be +written as a file inside the directory. Normally name of the file +inside the directory is computed as the basename of the \fIoutput\fR +file with \f(CW\*(C`.map\*(C'\fR appended. If however the special character +\&\f(CW\*(C`%\*(C'\fR is used then this will be replaced by the full path of the +output file. Additionally if there are any characters after the +\&\fI%\fR symbol then \f(CW\*(C`.map\*(C'\fR will no longer be appended. +.Sp +.Vb 10 +\& \-o foo.exe \-Map=bar [Creates ./bar] +\& \-o ../dir/foo.exe \-Map=bar [Creates ./bar] +\& \-o foo.exe \-Map=../dir [Creates ../dir/foo.exe.map] +\& \-o ../dir2/foo.exe \-Map=../dir [Creates ../dir/foo.exe.map] +\& \-o foo.exe \-Map=% [Creates ./foo.exe.map] +\& \-o ../dir/foo.exe \-Map=% [Creates ../dir/foo.exe.map] +\& \-o foo.exe \-Map=%.bar [Creates ./foo.exe.bar] +\& \-o ../dir/foo.exe \-Map=%.bar [Creates ../dir/foo.exe.bar] +\& \-o ../dir2/foo.exe \-Map=../dir/% [Creates ../dir/../dir2/foo.exe.map] +\& \-o ../dir2/foo.exe \-Map=../dir/%.bar [Creates ../dir/../dir2/foo.exe.bar] +.Ve +.Sp +It is an error to specify more than one \f(CW\*(C`%\*(C'\fR character. +.Sp +If the map file already exists then it will be overwritten by this +operation. +.IP \fB\-\-no\-keep\-memory\fR 4 +.IX Item "--no-keep-memory" +\&\fBld\fR normally optimizes for speed over memory usage by caching the +symbol tables of input files in memory. This option tells \fBld\fR to +instead optimize for memory usage, by rereading the symbol tables as +necessary. This may be required if \fBld\fR runs out of memory space +while linking a large executable. +.IP \fB\-\-no\-undefined\fR 4 +.IX Item "--no-undefined" +.PD 0 +.IP "\fB\-z defs\fR" 4 +.IX Item "-z defs" +.PD +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. +.Sp +The effects of this option can be reverted by using \f(CW\*(C`\-z undefs\*(C'\fR. +.IP \fB\-\-allow\-multiple\-definition\fR 4 +.IX Item "--allow-multiple-definition" +.PD 0 +.IP "\fB\-z muldefs\fR" 4 +.IX Item "-z muldefs" +.PD +Normally when a symbol is defined multiple times, the linker will +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" +.PD 0 +.IP \fB\-\-no\-allow\-shlib\-undefined\fR 4 +.IX Item "--no-allow-shlib-undefined" +.PD +Allows 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 default behaviour is to report errors for any undefined symbols +referenced in shared libraries if the linker is being used to create +an executable, but to allow them if the linker is being used to create +a shared library. +.Sp +The reasons for allowing undefined symbol references in shared +libraries specified at link time are that: +.RS 4 +.IP \(bu 4 +A shared library specified at link time may not be the same as the one +that is available at load time, so the symbol might actually be +resolvable at load time. +.IP \(bu 4 +There are some operating systems, eg BeOS and HPPA, where undefined +symbols in shared libraries are normal. +.Sp +The BeOS kernel for example patches shared libraries at load time to +select whichever function is most appropriate for the current +architecture. This is used, for example, to dynamically select an +appropriate memset function. +.RE +.RS 4 +.RE +.IP \fB\-\-error\-handling\-script=\fR\fIscriptname\fR 4 +.IX Item "--error-handling-script=scriptname" +If this option is provided then the linker will invoke +\&\fIscriptname\fR whenever an error is encountered. Currently however +only two kinds of error are supported: missing symbols and missing +libraries. Two arguments will be passed to script: the keyword +"undefined-symbol" or `missing\-lib" and the \fIname\fR of the +undefined symbol or missing library. The intention is that the script +will provide suggestions to the user as to where the symbol or library +might be found. After the script has finished then the normal linker +error message will be displayed. +.Sp +The availability of this option is controlled by a configure time +switch, so it may not be present in specific implementations. +.IP \fB\-\-no\-undefined\-version\fR 4 +.IX Item "--no-undefined-version" +Normally when a symbol has an undefined version, the linker will ignore +it. This option disallows symbols with undefined version and a fatal error +will be issued instead. +.IP \fB\-\-default\-symver\fR 4 +.IX Item "--default-symver" +Create and use a default symbol version (the soname) for unversioned +exported symbols. +.IP \fB\-\-default\-imported\-symver\fR 4 +.IX Item "--default-imported-symver" +Create and use a default symbol version (the soname) for unversioned +imported symbols. +.IP \fB\-\-no\-warn\-mismatch\fR 4 +.IX Item "--no-warn-mismatch" +Normally \fBld\fR will give an error if you try to link together input +files that are mismatched for some reason, perhaps because they have +been compiled for different processors or for different endiannesses. +This option tells \fBld\fR that it should silently permit such possible +errors. This option should only be used with care, in cases when you +have taken some special action that ensures that the linker errors are +inappropriate. +.IP \fB\-\-no\-warn\-search\-mismatch\fR 4 +.IX Item "--no-warn-search-mismatch" +Normally \fBld\fR will give a warning if it finds an incompatible +library during a library search. This option silences the warning. +.IP \fB\-\-no\-whole\-archive\fR 4 +.IX Item "--no-whole-archive" +Turn off the effect of the \fB\-\-whole\-archive\fR option for subsequent +archive files. +.IP \fB\-\-noinhibit\-exec\fR 4 +.IX Item "--noinhibit-exec" +Retain the executable output file whenever it is still usable. +Normally, the linker will not produce an output file if it encounters +errors during the link process; it exits without writing an output file +when it issues any error whatsoever. +.IP \fB\-nostdlib\fR 4 +.IX Item "-nostdlib" +Only search library directories explicitly specified on the +command line. Library directories specified in linker scripts +(including linker scripts specified on the command line) are ignored. +.IP \fB\-\-oformat=\fR\fIoutput-format\fR 4 +.IX Item "--oformat=output-format" +\&\fBld\fR may be configured to support more than one kind of object +file. If your \fBld\fR is configured this way, you can use the +\&\fB\-\-oformat\fR option to specify the binary format for the output +object file. Even when \fBld\fR is configured to support alternative +object formats, you don't usually need to specify this, as \fBld\fR +should be configured to produce as a default output format the most +usual format on each machine. \fIoutput-format\fR is a text string, the +name of a particular format supported by the BFD 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\-\-out\-implib\fR \fIfile\fR" 4 +.IX Item "--out-implib file" +Create an import library in \fIfile\fR corresponding to the executable +the linker is generating (eg. a DLL or ELF program). This import +library (which should be called \f(CW\*(C`*.dll.a\*(C'\fR or \f(CW\*(C`*.a\*(C'\fR for DLLs) +may be used to link clients against the generated executable; this +behaviour makes it possible to skip a separate import library creation +step (eg. \f(CW\*(C`dlltool\*(C'\fR for DLLs). This option is only available for +the i386 PE and ELF targetted ports of the linker. +.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 +ELF platforms. Position independent executables are similar to shared +libraries in that they are relocated by the dynamic linker to the virtual +address the OS 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\-no\-pie\fR 4 +.IX Item "-no-pie" +Create a position dependent executable. This is the default. +.IP \fB\-qmagic\fR 4 +.IX Item "-qmagic" +This option is ignored for Linux compatibility. +.IP \fB\-Qy\fR 4 +.IX Item "-Qy" +This option is ignored for SVR4 compatibility. +.IP \fB\-\-relax\fR 4 +.IX Item "--relax" +.PD 0 +.IP \fB\-\-no\-relax\fR 4 +.IX Item "--no-relax" +.PD +An option with machine dependent effects. +This option is only supported on a few targets. +.Sp +On some platforms the \fB\-\-relax\fR option performs target specific, +global optimizations that become possible when the linker resolves +addressing in the program, such as relaxing address modes, +synthesizing new instructions, selecting shorter version of current +instructions, and combining constant values. +.Sp +On some platforms these link time global optimizations may make symbolic +debugging of the resulting executable impossible. +This is known to be the case for the Matsushita MN10200 and MN10300 +family of processors. +.Sp +On platforms where the feature is supported, the option +\&\fB\-\-no\-relax\fR will disable it. +.Sp +On platforms where the feature is not supported, both \fB\-\-relax\fR +and \fB\-\-no\-relax\fR are accepted, but ignored. +.IP \fB\-\-retain\-symbols\-file=\fR\fIfilename\fR 4 +.IX Item "--retain-symbols-file=filename" +Retain \fIonly\fR the symbols listed in the file \fIfilename\fR, +discarding all others. \fIfilename\fR is simply a flat file, with one +symbol name per line. This option is especially useful in environments +(such as VxWorks) +where a large global symbol table is accumulated gradually, to conserve +run-time memory. +.Sp +\&\fB\-\-retain\-symbols\-file\fR does \fInot\fR discard undefined symbols, +or symbols needed for relocations. +.Sp +You may only specify \fB\-\-retain\-symbols\-file\fR once in the command +line. It overrides \fB\-s\fR and \fB\-S\fR. +.IP \fB\-rpath=\fR\fIdir\fR 4 +.IX Item "-rpath=dir" +Add a directory to the runtime library search path. This is used when +linking an ELF executable with shared objects. All \fB\-rpath\fR +arguments are concatenated and passed to the runtime linker, which uses +them to locate shared objects at runtime. +.Sp +The \fB\-rpath\fR option is also used when locating shared objects which +are needed by shared objects explicitly included in the link; see the +description of the \fB\-rpath\-link\fR option. Searching \fB\-rpath\fR +in this way is only supported by native linkers and cross linkers which +have been configured with the \fB\-\-with\-sysroot\fR option. +.Sp +If \fB\-rpath\fR is not used when linking an ELF executable, the +contents of the environment variable \f(CW\*(C`LD_RUN_PATH\*(C'\fR will be used if it +is defined. +.Sp +The \fB\-rpath\fR option may also be used on SunOS. By default, on +SunOS, the linker will form a runtime search path out of all the +\&\fB\-L\fR options it is given. If a \fB\-rpath\fR option is used, the +runtime search path will be formed exclusively using the \fB\-rpath\fR +options, ignoring the \fB\-L\fR options. This can be useful when using +gcc, which adds many \fB\-L\fR options which may be on NFS mounted +file systems. +.Sp +For compatibility with other ELF linkers, if the \fB\-R\fR option is +followed by a directory name, rather than a file name, it is treated as +the \fB\-rpath\fR option. +.IP \fB\-rpath\-link=\fR\fIdir\fR 4 +.IX Item "-rpath-link=dir" +When using ELF or SunOS, one shared library may require another. This +happens when an \f(CW\*(C`ld \-shared\*(C'\fR link includes a shared library as one +of the input files. +.Sp +When the linker encounters such a dependency when doing a non-shared, +non-relocatable link, it will automatically try to locate the required +shared library and include it in the link, if it is not included +explicitly. In such a case, the \fB\-rpath\-link\fR option +specifies the first set of directories to search. The +\&\fB\-rpath\-link\fR option may specify a sequence of directory names +either by specifying a list of names separated by colons, or by +appearing multiple times. +.Sp +The tokens \fR\f(CI$ORIGIN\fR\fI\fR and \fI\fR\f(CI$LIB\fR\fI\fR can appear in these search +directories. They will be replaced by the full path to the directory +containing the program or shared object in the case of \fI\fR\f(CI$ORIGIN\fR\fI\fR +and either \fBlib\fR \- for 32\-bit binaries \- or \fBlib64\fR \- for +64\-bit binaries \- in the case of \fI\fR\f(CI$LIB\fR\fI\fR. +.Sp +The alternative form of these tokens \- \fI${ORIGIN}\fR and +\&\fI${LIB}\fR can also be used. The token \fR\f(CI$PLATFORM\fR\fI\fR is not +supported. +.Sp +This option should be used with caution as it overrides the search path +that may have been hard compiled into a shared library. In such a case it +is possible to use unintentionally a different search path than the +runtime linker would do. +.Sp +The linker uses the following search paths to locate required shared +libraries: +.RS 4 +.IP 1. 4 +Any directories specified by \fB\-rpath\-link\fR options. +.IP 2. 4 +Any directories specified by \fB\-rpath\fR options. The difference +between \fB\-rpath\fR and \fB\-rpath\-link\fR is that directories +specified by \fB\-rpath\fR options are included in the executable and +used at runtime, whereas the \fB\-rpath\-link\fR option is only effective +at link time. Searching \fB\-rpath\fR in this way is only supported +by native linkers and cross linkers which have been configured with +the \fB\-\-with\-sysroot\fR option. +.IP 3. 4 +On an ELF system, for native linkers, if the \fB\-rpath\fR and +\&\fB\-rpath\-link\fR options were not used, search the contents of the +environment variable \f(CW\*(C`LD_RUN_PATH\*(C'\fR. +.IP 4. 4 +On SunOS, if the \fB\-rpath\fR option was not used, search any +directories specified using \fB\-L\fR options. +.IP 5. 4 +For a native linker, search the contents of the environment +variable \f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR. +.IP 6. 4 +For a native ELF linker, the directories in \f(CW\*(C`DT_RUNPATH\*(C'\fR or +\&\f(CW\*(C`DT_RPATH\*(C'\fR of a shared library are searched for shared +libraries needed by it. The \f(CW\*(C`DT_RPATH\*(C'\fR entries are ignored if +\&\f(CW\*(C`DT_RUNPATH\*(C'\fR entries exist. +.IP 7. 4 +For a linker for a Linux system, if the file \fI/etc/ld.so.conf\fR +exists, the list of directories found in that file. Note: the path +to this file is prefixed with the \f(CW\*(C`sysroot\*(C'\fR value, if that is +defined, and then any \f(CW\*(C`prefix\*(C'\fR string if the linker was +configured with the \fB\-\-prefix=<path>\fR option. +.IP 8. 4 +For a native linker on a FreeBSD system, any directories specified by +the \f(CW\*(C`_PATH_ELF_HINTS\*(C'\fR macro defined in the \fIelf\-hints.h\fR +header file. +.IP 9. 4 +Any directories specified by a \f(CW\*(C`SEARCH_DIR\*(C'\fR command in a +linker script given on the command line, including scripts specified +by \fB\-T\fR (but not \fB\-dT\fR). +.IP 10. 4 +The default directories, normally \fI/lib\fR and \fI/usr/lib\fR. +.IP 11. 4 +Any directories specified by a plugin LDPT_SET_EXTRA_LIBRARY_PATH. +.IP 12. 4 +Any directories specified by a \f(CW\*(C`SEARCH_DIR\*(C'\fR command in a default +linker script. +.RE +.RS 4 +.Sp +Note however on Linux based systems there is an additional caveat: If +the \fB\-\-as\-needed\fR option is active \fIand\fR a shared library +is located which would normally satisfy the search \fIand\fR this +library does not have DT_NEEDED tag for \fIlibc.so\fR +\&\fIand\fR there is a shared library later on in the set of search +directories which also satisfies the search \fIand\fR +this second shared library does have a DT_NEEDED tag for +\&\fIlibc.so\fR \fIthen\fR the second library will be selected instead +of the first. +.Sp +If the required shared library is not found, the linker will issue a +warning and continue with the link. +.RE +.IP \fB\-shared\fR 4 +.IX Item "-shared" +.PD 0 +.IP \fB\-Bshareable\fR 4 +.IX Item "-Bshareable" +.PD +Create a shared library. This is currently only supported on ELF, XCOFF +and SunOS platforms. On SunOS, the linker will automatically create a +shared library if the \fB\-e\fR option is not used and there are +undefined symbols in the link. +.IP \fB\-\-sort\-common\fR 4 +.IX Item "--sort-common" +.PD 0 +.IP \fB\-\-sort\-common=ascending\fR 4 +.IX Item "--sort-common=ascending" +.IP \fB\-\-sort\-common=descending\fR 4 +.IX Item "--sort-common=descending" +.PD +This option tells \fBld\fR to sort the common symbols by alignment in +ascending or descending order when it places them in the appropriate output +sections. The symbol alignments considered are sixteen-byte or larger, +eight-byte, four-byte, two-byte, and one-byte. This is to prevent gaps +between symbols due to alignment constraints. If no sorting order is +specified, then descending order is assumed. +.IP \fB\-\-sort\-section=name\fR 4 +.IX Item "--sort-section=name" +This option will apply \f(CW\*(C`SORT_BY_NAME\*(C'\fR to all wildcard section +patterns in the linker script. +.IP \fB\-\-sort\-section=alignment\fR 4 +.IX Item "--sort-section=alignment" +This option will apply \f(CW\*(C`SORT_BY_ALIGNMENT\*(C'\fR to all wildcard section +patterns in the linker script. +.IP \fB\-\-spare\-dynamic\-tags=\fR\fIcount\fR 4 +.IX Item "--spare-dynamic-tags=count" +This option specifies the number of empty slots to leave in the +\&.dynamic section of ELF shared objects. Empty slots may be needed by +post processing tools, such as the prelinker. The default is 5. +.IP \fB\-\-split\-by\-file[=\fR\fIsize\fR\fB]\fR 4 +.IX Item "--split-by-file[=size]" +Similar to \fB\-\-split\-by\-reloc\fR but creates a new output section for +each input file when \fIsize\fR is reached. \fIsize\fR defaults to a +size of 1 if not given. +.IP \fB\-\-split\-by\-reloc[=\fR\fIcount\fR\fB]\fR 4 +.IX Item "--split-by-reloc[=count]" +Tries to creates extra sections in the output file so that no single +output section in the file contains more than \fIcount\fR relocations. +This is useful when generating huge relocatable files for downloading into +certain real time kernels with the COFF object file format; since COFF +cannot represent more than 65535 relocations in a single section. Note +that this will fail to work with object file formats which do not +support arbitrary sections. The linker will not split up individual +input sections for redistribution, so if a single input section contains +more than \fIcount\fR relocations one output section will contain that +many relocations. \fIcount\fR defaults to a value of 32768. +.IP \fB\-\-stats\fR 4 +.IX Item "--stats" +Compute and display statistics about the operation of the linker, such +as execution time and memory usage. +.IP \fB\-\-sysroot=\fR\fIdirectory\fR 4 +.IX Item "--sysroot=directory" +Use \fIdirectory\fR as the location of the sysroot, overriding the +configure-time default. This option is only supported by linkers +that were configured using \fB\-\-with\-sysroot\fR. +.IP \fB\-\-task\-link\fR 4 +.IX Item "--task-link" +This is used by COFF/PE based targets to create a task-linked object +file where all of the global symbols have been converted to statics. +.IP \fB\-\-traditional\-format\fR 4 +.IX Item "--traditional-format" +For some targets, the output of \fBld\fR is different in some ways from +the output of some existing linker. This switch requests \fBld\fR to +use the traditional format instead. +.Sp +For example, on SunOS, \fBld\fR combines duplicate entries in the +symbol string table. This can reduce the size of an output file with +full debugging information by over 30 percent. Unfortunately, the SunOS +\&\f(CW\*(C`dbx\*(C'\fR program can not read the resulting program (\f(CW\*(C`gdb\*(C'\fR has no +trouble). The \fB\-\-traditional\-format\fR switch tells \fBld\fR to not +combine duplicate entries. +.IP \fB\-\-section\-start=\fR\fIsectionname\fR\fB=\fR\fIorg\fR 4 +.IX Item "--section-start=sectionname=org" +Locate a section in the output file at the absolute +address given by \fIorg\fR. You may use this option as many +times as necessary to locate multiple sections in the command +line. +\&\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. \fINote:\fR there +should be no white space between \fIsectionname\fR, the equals +sign ("\fB=\fR"), and \fIorg\fR. +.IP \fB\-Tbss=\fR\fIorg\fR 4 +.IX Item "-Tbss=org" +.PD 0 +.IP \fB\-Tdata=\fR\fIorg\fR 4 +.IX Item "-Tdata=org" +.IP \fB\-Ttext=\fR\fIorg\fR 4 +.IX Item "-Ttext=org" +.PD +Same as \fB\-\-section\-start\fR, 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\-Ttext\-segment=\fR\fIorg\fR 4 +.IX Item "-Ttext-segment=org" +When creating an ELF executable, it will set the address of the first +byte of the text segment. +.IP \fB\-Trodata\-segment=\fR\fIorg\fR 4 +.IX Item "-Trodata-segment=org" +When creating an ELF executable or shared object for a target where +the read-only data is in its own segment separate from the executable +text, it will set the address of the first byte of the read-only data segment. +.IP \fB\-Tldata\-segment=\fR\fIorg\fR 4 +.IX Item "-Tldata-segment=org" +When creating an ELF executable or shared object for x86\-64 medium memory +model, it will set the address of the first byte of the ldata segment. +.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 +.IP \fB\-\-verbose[=\fR\fINUMBER\fR\fB]\fR 4 +.IX Item "--verbose[=NUMBER]" +.PD +Display the version number for \fBld\fR and list the linker emulations +supported. Display which input files can and cannot be opened. Display +the linker script being used by the linker. If the optional \fINUMBER\fR +argument > 1, plugin symbol status will also be displayed. +.IP \fB\-\-version\-script=\fR\fIversion-scriptfile\fR 4 +.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 hierarchy for the library being created. This option +is only fully supported on ELF platforms which support shared libraries; +see \fBVERSION\fR. It is partially supported on PE platforms, which can +use version scripts to filter symbol visibility in auto-export mode: any +symbols marked \fBlocal\fR in the version script will not be exported. +.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, +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 +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: +.RS 4 +.IP "\fBint i = 1;\fR" 4 +.IX Item "int i = 1;" +A definition, which goes in the initialized data section of the output +file. +.IP "\fBextern int i;\fR" 4 +.IX Item "extern int i;" +An undefined reference, which does not allocate space. +There must be either a definition or a common symbol for the +variable somewhere. +.IP "\fBint i;\fR" 4 +.IX Item "int i;" +A common symbol. If there are only (one or more) common symbols for a +variable, it goes in the uninitialized data area of the output file. +The linker merges multiple common symbols for the same variable into a +single symbol. If they are of different sizes, it picks the largest +size. The linker turns a common symbol into a declaration, if there is +a definition of the same variable. +.RE +.RS 4 +.Sp +The \fB\-\-warn\-common\fR option can produce five kinds of warnings. +Each warning consists of a pair of lines: the first describes the symbol +just encountered, and the second describes the previous symbol +encountered with the same name. One or both of the two symbols will be +a common symbol. +.IP 1. 4 +Turning a common symbol into a reference, because there is already a +definition for the symbol. +.Sp +.Vb 3 +\& <file>(<section>): warning: common of \`<symbol>\*(Aq +\& overridden by definition +\& <file>(<section>): warning: defined here +.Ve +.IP 2. 4 +Turning a common symbol into a reference, because a later definition for +the symbol is encountered. This is the same as the previous case, +except that the symbols are encountered in a different order. +.Sp +.Vb 3 +\& <file>(<section>): warning: definition of \`<symbol>\*(Aq +\& overriding common +\& <file>(<section>): warning: common is here +.Ve +.IP 3. 4 +Merging a common symbol with a previous same-sized common symbol. +.Sp +.Vb 3 +\& <file>(<section>): warning: multiple common +\& of \`<symbol>\*(Aq +\& <file>(<section>): warning: previous common is here +.Ve +.IP 4. 4 +Merging a common symbol with a previous larger common symbol. +.Sp +.Vb 3 +\& <file>(<section>): warning: common of \`<symbol>\*(Aq +\& overridden by larger common +\& <file>(<section>): warning: larger common is here +.Ve +.IP 5. 4 +Merging a common symbol with a previous smaller common symbol. This is +the same as the previous case, except that the symbols are +encountered in a different order. +.Sp +.Vb 3 +\& <file>(<section>): warning: common of \`<symbol>\*(Aq +\& overriding smaller common +\& <file>(<section>): warning: smaller common is here +.Ve +.RE +.RS 4 +.RE +.IP \fB\-\-warn\-constructors\fR 4 +.IX Item "--warn-constructors" +Warn if any global constructors are used. This is only useful for a few +object file formats. For formats like COFF or ELF, the linker can not +detect the use of global constructors. +.IP \fB\-\-warn\-execstack\fR 4 +.IX Item "--warn-execstack" +.PD 0 +.IP \fB\-\-warn\-execstack\-objects\fR 4 +.IX Item "--warn-execstack-objects" +.IP \fB\-\-no\-warn\-execstack\fR 4 +.IX Item "--no-warn-execstack" +.PD +On ELF platforms the linker may generate warning messages if it is +asked to create an output file that contains an executable stack. +There are three possible states: +.RS 4 +.IP 1. 4 +Do not generate any warnings. +.IP 2. 4 +Always generate warnings, even if the executable stack is requested +via the \fB\-z execstack\fR command line option. +.IP 3. 4 +Only generate a warning if an object file requests an executable +stack, but not if the \fB\-z execstack\fR option is used. +.RE +.RS 4 +.Sp +The default state depends upon how the linker was configured when it +was built. The \fB\-\-no\-warn\-execstack\fR option always puts the +linker into the no-warnings state. The \fB\-\-warn\-execstack\fR +option puts the linker into the warn-always state. The +\&\fB\-\-warn\-execstack\-objects\fR option puts the linker into the +warn-for-object-files-only state. +.Sp +Note: ELF format input files can specify that they need an executable +stack by having a \fI.note.GNU\-stack\fR section with the executable +bit set in its section flags. They can specify that they do not need +an executable stack by having the same section, but without the +executable flag bit set. If an input file does not have a +\&\fI.note.GNU\-stack\fR section then the default behaviour is target +specific. For some targets, then absence of such a section implies +that an executable stack \fIis\fR required. This is often a problem +for hand crafted assembler files. +.RE +.IP \fB\-\-error\-execstack\fR 4 +.IX Item "--error-execstack" +.PD 0 +.IP \fB\-\-no\-error\-execstack\fR 4 +.IX Item "--no-error-execstack" +.PD +If the linker is going to generate a warning message about an +executable stack then the \fB\-\-error\-execstack\fR option will +instead change that warning into an error. Note \- this option does +not change the linker's execstack warning generation state. Use +\&\fB\-\-warn\-execstack\fR or \fB\-\-warn\-execstack\-objects\fR to set +a specific warning state. +.Sp +The \fB\-\-no\-error\-execstack\fR option will restore the default +behaviour of generating warning messages. +.IP \fB\-\-warn\-multiple\-gp\fR 4 +.IX Item "--warn-multiple-gp" +Warn if multiple global pointer values are required in the output file. +This is only meaningful for certain processors, such as the Alpha. +Specifically, some processors put large-valued constants in a special +section. A special register (the global pointer) points into the middle +of this section, so that constants can be loaded efficiently via a +base-register relative addressing mode. Since the offset in +base-register relative mode is fixed and relatively small (e.g., 16 +bits), this limits the maximum size of the constant pool. Thus, in +large programs, it is often necessary to use multiple global pointer +values in order to be able to address all possible constants. This +option causes a warning to be issued whenever this case occurs. +.IP \fB\-\-warn\-once\fR 4 +.IX Item "--warn-once" +Only warn once for each undefined symbol, rather than once per module +which refers to it. +.IP \fB\-\-warn\-rwx\-segments\fR 4 +.IX Item "--warn-rwx-segments" +.PD 0 +.IP \fB\-\-no\-warn\-rwx\-segments\fR 4 +.IX Item "--no-warn-rwx-segments" +.PD +Warn if the linker creates a loadable, non-zero sized segment that has +all three of the read, write and execute permission flags set. Such a +segment represents a potential security vulnerability. In addition +warnings will be generated if a thread local storage segment is +created with the execute permission flag set, regardless of whether or +not it has the read and/or write flags set. +.Sp +These warnings are enabled by default. They can be disabled via the +\&\fB\-\-no\-warn\-rwx\-segments\fR option and re-enabled via the +\&\fB\-\-warn\-rwx\-segments\fR option. +.IP \fB\-\-error\-rwx\-segments\fR 4 +.IX Item "--error-rwx-segments" +.PD 0 +.IP \fB\-\-no\-error\-rwx\-segments\fR 4 +.IX Item "--no-error-rwx-segments" +.PD +If the linker is going to generate a warning message about an +executable, writeable segment, or an executable TLS segment, then the +\&\fB\-\-error\-rwx\-segments\fR option will turn this warning into an +error instead. The \fB\-\-no\-error\-rwx\-segments\fR option will +restore the default behaviour of just generating a warning message. +.Sp +Note \- the \fB\-\-error\-rwx\-segments\fR option does not by itself +turn on warnings about these segments. These warnings are either +enabled by default, if the linker was configured that way, or via the +\&\fB\-\-warn\-rwx\-segments\fR command line option. +.IP \fB\-\-warn\-section\-align\fR 4 +.IX Item "--warn-section-align" +Warn if the address of an output section is changed because of +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\-textrel\fR 4 +.IX Item "--warn-textrel" +Warn if the linker adds DT_TEXTREL to a position-independent executable +or shared object. +.IP \fB\-\-warn\-alternate\-em\fR 4 +.IX Item "--warn-alternate-em" +Warn if an object has alternate ELF machine code. +.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 +\&\fB\-\-whole\-archive\fR option, include every object file in the archive +in the link, rather than searching the archive for the required object +files. This is normally used to turn an archive file into a shared +library, forcing every object to be included in the resulting shared +library. This option may be used more than once. +.Sp +Two notes when using this option from gcc: First, gcc doesn't know +about this option, so you have to use \fB\-Wl,\-whole\-archive\fR. +Second, don't forget to use \fB\-Wl,\-no\-whole\-archive\fR after your +list of archives, because gcc will add its own list of archives to +your link and you may not want this flag to affect those as well. +.IP \fB\-\-wrap=\fR\fIsymbol\fR 4 +.IX Item "--wrap=symbol" +Use a wrapper function for \fIsymbol\fR. Any undefined reference to +\&\fIsymbol\fR will be resolved to \f(CW\*(C`_\|_wrap_\fR\f(CIsymbol\fR\f(CW\*(C'\fR. Any +undefined reference to \f(CW\*(C`_\|_real_\fR\f(CIsymbol\fR\f(CW\*(C'\fR will be resolved to +\&\fIsymbol\fR. +.Sp +This can be used to provide a wrapper for a system function. The +wrapper function should be called \f(CW\*(C`_\|_wrap_\fR\f(CIsymbol\fR\f(CW\*(C'\fR. If it +wishes to call the system function, it should call +\&\f(CW\*(C`_\|_real_\fR\f(CIsymbol\fR\f(CW\*(C'\fR. +.Sp +Here is a trivial example: +.Sp +.Vb 6 +\& void * +\& _\|_wrap_malloc (size_t c) +\& { +\& printf ("malloc called with %zu\en", c); +\& return _\|_real_malloc (c); +\& } +.Ve +.Sp +If you link other code with this file using \fB\-\-wrap malloc\fR, then +all calls to \f(CW\*(C`malloc\*(C'\fR will call the function \f(CW\*(C`_\|_wrap_malloc\*(C'\fR +instead. The call to \f(CW\*(C`_\|_real_malloc\*(C'\fR in \f(CW\*(C`_\|_wrap_malloc\*(C'\fR will +call the real \f(CW\*(C`malloc\*(C'\fR function. +.Sp +You may wish to provide a \f(CW\*(C`_\|_real_malloc\*(C'\fR function as well, so that +links without the \fB\-\-wrap\fR option will succeed. If you do this, +you should not put the definition of \f(CW\*(C`_\|_real_malloc\*(C'\fR in the same +file as \f(CW\*(C`_\|_wrap_malloc\*(C'\fR; if you do, the assembler may resolve the +call before the linker has a chance to wrap it to \f(CW\*(C`malloc\*(C'\fR. +.Sp +Only undefined references are replaced by the linker. So, translation unit +internal references to \fIsymbol\fR are not resolved to +\&\f(CW\*(C`_\|_wrap_\fR\f(CIsymbol\fR\f(CW\*(C'\fR. In the next example, the call to \f(CW\*(C`f\*(C'\fR in +\&\f(CW\*(C`g\*(C'\fR is not resolved to \f(CW\*(C`_\|_wrap_f\*(C'\fR. +.Sp +.Vb 5 +\& int +\& f (void) +\& { +\& return 123; +\& } +\& +\& int +\& g (void) +\& { +\& return f(); +\& } +.Ve +.IP \fB\-\-eh\-frame\-hdr\fR 4 +.IX Item "--eh-frame-hdr" +.PD 0 +.IP \fB\-\-no\-eh\-frame\-hdr\fR 4 +.IX Item "--no-eh-frame-hdr" +.PD +Request (\fB\-\-eh\-frame\-hdr\fR) or suppress +(\fB\-\-no\-eh\-frame\-hdr\fR) the creation of \f(CW\*(C`.eh_frame_hdr\*(C'\fR +section and ELF \f(CW\*(C`PT_GNU_EH_FRAME\*(C'\fR segment header. +.IP \fB\-\-no\-ld\-generated\-unwind\-info\fR 4 +.IX Item "--no-ld-generated-unwind-info" +Request creation of \f(CW\*(C`.eh_frame\*(C'\fR unwind info for linker +generated code sections like PLT. This option is on by default +if linker generated unwind info is supported. This option also +controls the generation of \f(CW\*(C`.sframe\*(C'\fR stack trace info for linker +generated code sections like PLT. +.IP \fB\-\-enable\-new\-dtags\fR 4 +.IX Item "--enable-new-dtags" +.PD 0 +.IP \fB\-\-disable\-new\-dtags\fR 4 +.IX Item "--disable-new-dtags" +.PD +This linker can create the new dynamic tags in ELF. But the older ELF +systems may not understand them. If you specify +\&\fB\-\-enable\-new\-dtags\fR, the new dynamic tags will be created as needed +and older dynamic tags will be omitted. +If you specify \fB\-\-disable\-new\-dtags\fR, no new dynamic tags will be +created. By default, the new dynamic tags are created. Note that +those options are only available for ELF systems. +.IP \fB\-\-hash\-size=\fR\fInumber\fR 4 +.IX Item "--hash-size=number" +Set the default size of the linker's hash tables to a prime number +close to \fInumber\fR. Increasing this value can reduce the length of +time it takes the linker to perform its tasks, at the expense of +increasing the linker's memory requirements. Similarly reducing this +value can reduce the memory requirements at the expense of speed. +.IP \fB\-\-hash\-style=\fR\fIstyle\fR 4 +.IX Item "--hash-style=style" +Set the type of linker's hash table(s). \fIstyle\fR can be either +\&\f(CW\*(C`sysv\*(C'\fR for classic ELF \f(CW\*(C`.hash\*(C'\fR section, \f(CW\*(C`gnu\*(C'\fR for +new style GNU \f(CW\*(C`.gnu.hash\*(C'\fR section or \f(CW\*(C`both\*(C'\fR for both +the classic ELF \f(CW\*(C`.hash\*(C'\fR and new style GNU \f(CW\*(C`.gnu.hash\*(C'\fR +hash tables. The default depends upon how the linker was configured, +but for most Linux based systems it will be \f(CW\*(C`both\*(C'\fR. +.IP \fB\-\-compress\-debug\-sections=none\fR 4 +.IX Item "--compress-debug-sections=none" +.PD 0 +.IP \fB\-\-compress\-debug\-sections=zlib\fR 4 +.IX Item "--compress-debug-sections=zlib" +.IP \fB\-\-compress\-debug\-sections=zlib\-gnu\fR 4 +.IX Item "--compress-debug-sections=zlib-gnu" +.IP \fB\-\-compress\-debug\-sections=zlib\-gabi\fR 4 +.IX Item "--compress-debug-sections=zlib-gabi" +.IP \fB\-\-compress\-debug\-sections=zstd\fR 4 +.IX Item "--compress-debug-sections=zstd" +.PD +On ELF platforms, these options control how DWARF debug sections are +compressed using zlib. +.Sp +\&\fB\-\-compress\-debug\-sections=none\fR doesn't compress DWARF debug +sections. \fB\-\-compress\-debug\-sections=zlib\-gnu\fR compresses +DWARF debug sections and renames them to begin with \fB.zdebug\fR +instead of \fB.debug\fR. \fB\-\-compress\-debug\-sections=zlib\-gabi\fR +also compresses DWARF debug sections, but rather than renaming them it +sets the SHF_COMPRESSED flag in the sections' headers. +.Sp +The \fB\-\-compress\-debug\-sections=zlib\fR option is an alias for +\&\fB\-\-compress\-debug\-sections=zlib\-gabi\fR. +.Sp +\&\fB\-\-compress\-debug\-sections=zstd\fR compresses DWARF debug sections using +zstd. +.Sp +Note that this option overrides any compression in input debug +sections, so if a binary is linked with \fB\-\-compress\-debug\-sections=none\fR +for example, then any compressed debug sections in input files will be +uncompressed before they are copied into the output binary. +.Sp +The default compression behaviour varies depending upon the target +involved and the configure options used to build the toolchain. The +default can be determined by examining the output from the linker's +\&\fB\-\-help\fR option. +.IP \fB\-\-reduce\-memory\-overheads\fR 4 +.IX Item "--reduce-memory-overheads" +This option reduces memory requirements at ld runtime, at the expense of +linking speed. This was introduced to select the old O(n^2) algorithm +for link map file generation, rather than the new O(n) algorithm which uses +about 40% more memory for symbol storage. +.Sp +Another effect of the switch is to set the default hash table size to +1021, which again saves memory at the cost of lengthening the linker's +run time. This is not done however if the \fB\-\-hash\-size\fR switch +has been used. +.Sp +The \fB\-\-reduce\-memory\-overheads\fR switch may be also be used to +enable other tradeoffs in future versions of the linker. +.IP \fB\-\-max\-cache\-size=\fR\fIsize\fR 4 +.IX Item "--max-cache-size=size" +\&\fBld\fR normally caches the relocation information and symbol tables +of input files in memory with the unlimited size. This option sets the +maximum cache size to \fIsize\fR. +.IP \fB\-\-build\-id\fR 4 +.IX Item "--build-id" +.PD 0 +.IP \fB\-\-build\-id=\fR\fIstyle\fR 4 +.IX Item "--build-id=style" +.PD +Request the creation of a \f(CW\*(C`.note.gnu.build\-id\*(C'\fR ELF note section +or a \f(CW\*(C`.buildid\*(C'\fR COFF section. The contents of the note are +unique bits identifying this linked file. \fIstyle\fR can be +\&\f(CW\*(C`uuid\*(C'\fR to use 128 random bits, \f(CW\*(C`sha1\*(C'\fR to use a 160\-bit +SHA1 hash on the normative parts of the output contents, +\&\f(CW\*(C`md5\*(C'\fR to use a 128\-bit MD5 hash on the normative parts of +the output contents, or \f(CW\*(C`0x\fR\f(CIhexstring\fR\f(CW\*(C'\fR to use a chosen bit +string specified as an even number of hexadecimal digits (\f(CW\*(C`\-\*(C'\fR and +\&\f(CW\*(C`:\*(C'\fR characters between digit pairs are ignored). If \fIstyle\fR +is omitted, \f(CW\*(C`sha1\*(C'\fR is used. +.Sp +The \f(CW\*(C`md5\*(C'\fR and \f(CW\*(C`sha1\*(C'\fR styles produces an identifier +that is always the same in an identical output file, but will be +unique among all nonidentical output files. It is not intended +to be compared as a checksum for the file's contents. A linked +file may be changed later by other tools, but the build ID bit +string identifying the original linked file does not change. +.Sp +Passing \f(CW\*(C`none\*(C'\fR for \fIstyle\fR disables the setting from any +\&\f(CW\*(C`\-\-build\-id\*(C'\fR options earlier on the command line. +.IP \fB\-\-package\-metadata=\fR\fIJSON\fR 4 +.IX Item "--package-metadata=JSON" +Request the creation of a \f(CW\*(C`.note.package\*(C'\fR ELF note section. The +contents of the note are in JSON format, as per the package metadata +specification. For more information see: +https://systemd.io/ELF_PACKAGE_METADATA/ +If the JSON argument is missing/empty then this will disable the +creation of the metadata note, if one had been enabled by an earlier +occurrence of the \-\-package\-metdata option. +If the linker has been built with libjansson, then the JSON string +will be validated. +.PP +The i386 PE linker supports the \fB\-shared\fR option, which causes +the output to be a dynamically linked library (DLL) instead of a +normal executable. You should name the output \f(CW\*(C`*.dll\*(C'\fR when you +use this option. In addition, the linker fully supports the standard +\&\f(CW\*(C`*.def\*(C'\fR files, which may be specified on the linker command line +like an object file (in fact, it should precede archives it exports +symbols from, to ensure that they get linked in, just like a normal +object file). +.PP +In addition to the options common to all targets, the i386 PE linker +support additional command-line options that are specific to the i386 +PE target. Options that take values may be separated from their +values by either a space or an equals sign. +.IP \fB\-\-add\-stdcall\-alias\fR 4 +.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 PE 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 PE specific option] +.IP \fB\-\-dll\fR 4 +.IX Item "--dll" +Create a DLL 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 PE targeted port of the linker] +.IP \fB\-\-enable\-long\-section\-names\fR 4 +.IX Item "--enable-long-section-names" +.PD 0 +.IP \fB\-\-disable\-long\-section\-names\fR 4 +.IX Item "--disable-long-section-names" +.PD +The PE variants of the COFF object format add an extension that permits +the use of section names longer than eight characters, the normal limit +for COFF. By default, these names are only allowed in object files, as +fully-linked executable images do not carry the COFF string table required +to support the longer names. As a GNU extension, it is possible to +allow their use in executable images as well, or to (probably pointlessly!) +disallow it in object files, by using these two options. Executable images +generated with these long section names are slightly non-standard, carrying +as they do a string table, and may generate confusing output when examined +with non-GNU PE-aware tools, such as file viewers and dumpers. However, +GDB relies on the use of PE long section names to find Dwarf\-2 debug +information sections in an executable image at runtime, and so if neither +option is specified on the command-line, \fBld\fR will enable long +section names, overriding the default and technically correct behaviour, +when it finds the presence of debug information while linking an executable +image and not stripping symbols. +[This option is valid for all PE targeted ports of the linker] +.IP \fB\-\-enable\-stdcall\-fixup\fR 4 +.IX Item "--enable-stdcall-fixup" +.PD 0 +.IP \fB\-\-disable\-stdcall\-fixup\fR 4 +.IX Item "--disable-stdcall-fixup" +.PD +If the link finds a symbol that it cannot resolve, it will attempt to +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 +\&\f(CW\*(C`_foo@12\*(C'\fR, or the undefined symbol \f(CW\*(C`_bar@16\*(C'\fR might be linked +to the function \f(CW\*(C`_bar\*(C'\fR. When the linker does this, it prints a +warning, since it normally should have failed to link, but sometimes +import libraries generated from third-party dlls may need this feature +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 PE targeted port of the linker] +.IP \fB\-\-leading\-underscore\fR 4 +.IX Item "--leading-underscore" +.PD 0 +.IP \fB\-\-no\-leading\-underscore\fR 4 +.IX Item "--no-leading-underscore" +.PD +For most targets default symbol-prefix is an underscore and is defined +in target's description. By this option it is possible to +disable/enable the default underscore symbol-prefix. +.IP \fB\-\-export\-all\-symbols\fR 4 +.IX Item "--export-all-symbols" +If given, all global symbols in the objects used to build a DLL will +be exported by the DLL. Note that this is the default if there +otherwise wouldn't be any exported symbols. When symbols are +explicitly exported via DEF files or implicitly exported via function +attributes, the default is to not export anything else unless this +option is given. Note that the symbols \f(CW\*(C`DllMain@12\*(C'\fR, +\&\f(CW\*(C`DllEntryPoint@0\*(C'\fR, \f(CW\*(C`DllMainCRTStartup@12\*(C'\fR, and +\&\f(CW\*(C`impure_ptr\*(C'\fR will not be automatically +exported. Also, symbols imported from other DLLs will not be +re-exported, nor will symbols specifying the DLL's internal layout +such as those beginning with \f(CW\*(C`_head_\*(C'\fR or ending with +\&\f(CW\*(C`_iname\*(C'\fR. In addition, no symbols from \f(CW\*(C`libgcc\*(C'\fR, +\&\f(CW\*(C`libstd++\*(C'\fR, \f(CW\*(C`libmingw32\*(C'\fR, or \f(CW\*(C`crtX.o\*(C'\fR will be exported. +Symbols whose names begin with \f(CW\*(C`_\|_rtti_\*(C'\fR or \f(CW\*(C`_\|_builtin_\*(C'\fR will +not be exported, to help with C++ DLLs. Finally, there is an +extensive list of cygwin-private symbols that are not exported +(obviously, this applies on when building DLLs for cygwin targets). +These cygwin-excludes are: \f(CW\*(C`_cygwin_dll_entry@12\*(C'\fR, +\&\f(CW\*(C`_cygwin_crt0_common@8\*(C'\fR, \f(CW\*(C`_cygwin_noncygwin_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 PE 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 PE targeted port of the linker] +.IP \fB\-\-exclude\-all\-symbols\fR 4 +.IX Item "--exclude-all-symbols" +Specifies no symbols should be automatically exported. +[This option is specific to the i386 PE 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 PE targeted port of the linker] +.IP "\fB\-\-heap\fR \fIreserve\fR" 4 +.IX Item "--heap reserve" +.PD 0 +.IP "\fB\-\-heap\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4 +.IX Item "--heap reserve,commit" +.PD +Specify the number of bytes 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 PE 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 +the lowest memory location that will be used when your program or dll +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 PE 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 PE targeted port of the linker] +.IP \fB\-\-large\-address\-aware\fR 4 +.IX Item "--large-address-aware" +If given, the appropriate bit in the "Characteristics" field of the COFF +header is set to indicate that this executable supports virtual addresses +greater than 2 gigabytes. This should be used in conjunction with the /3GB +or /USERVA=\fIvalue\fR megabytes switch in the "[operating systems]" +section of the BOOT.INI. Otherwise, this bit has no effect. +[This option is specific to PE targeted ports of the linker] +.IP \fB\-\-disable\-large\-address\-aware\fR 4 +.IX Item "--disable-large-address-aware" +Reverts the effect of a previous \fB\-\-large\-address\-aware\fR option. +This is useful if \fB\-\-large\-address\-aware\fR is always set by the compiler +driver (e.g. Cygwin gcc) and the executable does not support virtual +addresses greater than 2 gigabytes. +[This option is specific to PE targeted ports of the linker] +.IP "\fB\-\-major\-image\-version\fR \fIvalue\fR" 4 +.IX Item "--major-image-version value" +Sets the major number of the "image version". Defaults to 1. +[This option is specific to the i386 PE 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 "os version". Defaults to 4. +[This option is specific to the i386 PE 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 "subsystem version". Defaults to 4. +[This option is specific to the i386 PE 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 "image version". Defaults to 0. +[This option is specific to the i386 PE 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 "os version". Defaults to 0. +[This option is specific to the i386 PE 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 "subsystem version". Defaults to 0. +[This option is specific to the i386 PE 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 DEF +file corresponding to the DLL the linker is generating. This DEF file +(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 PE targeted port of the linker] +.IP \fB\-\-enable\-auto\-image\-base\fR 4 +.IX Item "--enable-auto-image-base" +.PD 0 +.IP \fB\-\-enable\-auto\-image\-base=\fR\fIvalue\fR 4 +.IX Item "--enable-auto-image-base=value" +.PD +Automatically choose the image base for DLLs, optionally starting with base +\&\fIvalue\fR, unless one is specified 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 DLL, in-memory collisions and relocations which can delay program +execution are avoided. +[This option is specific to the i386 PE 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 PE 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, +search for \f(CW\*(C`<string><basename>.dll\*(C'\fR in preference to +\&\f(CW\*(C`lib<basename>.dll\*(C'\fR. This behaviour allows easy distinction +between DLLs built for the various "subplatforms": 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 PE 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 +DATA imports from DLLs, thus making it possible to bypass the dllimport +mechanism on the user side and to reference unmangled symbol names. +[This option is specific to the i386 PE targeted port of the linker] +.Sp +The following remarks pertain to the original implementation of the +feature and are obsolete nowadays for Cygwin and MinGW targets. +.Sp +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 +Note \- use of the 'auto\-import' extension will also cause read only +data which would normally be placed into the .rdata section to be +placed into the .data section instead. This is in order to work +around a problem with consts that is described here: +http://www.cygwin.com/ml/cygwin/2004\-09/msg01101.html +.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." +.Sp +This message occurs when some (sub)expression accesses an address +ultimately given by the sum of two constants (Win32 import tables only +allow one). Instances where this may occur include accesses to member +fields of struct variables imported from a DLL, as well as using a +constant index into an array variable imported from a DLL. Any +multiword variable (arrays, structs, long long, etc) may trigger +this error condition. However, regardless of the exact data type +of the offending exported variable, ld will always detect it, issue +the warning, and exit. +.Sp +There are several ways to address this difficulty, regardless of the +data type of the exported variable: +.Sp +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: +.Sp +.Vb 3 +\& extern type extern_array[]; +\& extern_array[1] \-\-> +\& { volatile type *t=extern_array; t[1] } +.Ve +.Sp +or +.Sp +.Vb 3 +\& extern type extern_array[]; +\& extern_array[1] \-\-> +\& { volatile int t=1; extern_array[t] } +.Ve +.Sp +For structs (and most other multiword data types) the only option +is to make the struct itself (or the long long, or the ...) variable: +.Sp +.Vb 3 +\& extern struct s extern_struct; +\& extern_struct.field \-\-> +\& { volatile struct s *t=&extern_struct; t\->field } +.Ve +.Sp +or +.Sp +.Vb 3 +\& extern long long extern_ll; +\& extern_ll \-\-> +\& { volatile long long * local_ll=&extern_ll; *local_ll } +.Ve +.Sp +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 +requires using compile-time #defines to indicate whether you are +building a DLL, building client code that will link to the DLL, or +merely building/linking to a static library. In making the choice +between the various methods of resolving the 'direct address with +constant offset' problem, you should consider typical real-world usage: +.Sp +Original: +.Sp +.Vb 7 +\& \-\-foo.h +\& extern int arr[]; +\& \-\-foo.c +\& #include "foo.h" +\& void main(int argc, char **argv){ +\& printf("%d\en",arr[1]); +\& } +.Ve +.Sp +Solution 1: +.Sp +.Vb 9 +\& \-\-foo.h +\& extern int arr[]; +\& \-\-foo.c +\& #include "foo.h" +\& void main(int argc, char **argv){ +\& /* This workaround is for win32 and cygwin; do not "optimize" */ +\& volatile int *parr = arr; +\& printf("%d\en",parr[1]); +\& } +.Ve +.Sp +Solution 2: +.Sp +.Vb 10 +\& \-\-foo.h +\& /* Note: auto\-export is assumed (no _\|_declspec(dllexport)) */ +\& #if (defined(_WIN32) || defined(_\|_CYGWIN_\|_)) && \e +\& !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC)) +\& #define FOO_IMPORT _\|_declspec(dllimport) +\& #else +\& #define FOO_IMPORT +\& #endif +\& extern FOO_IMPORT int arr[]; +\& \-\-foo.c +\& #include "foo.h" +\& void main(int argc, char **argv){ +\& printf("%d\en",arr[1]); +\& } +.Ve +.Sp +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. \fBset_foo()\fR and \fBget_foo()\fR accessor +functions). +.IP \fB\-\-disable\-auto\-import\fR 4 +.IX Item "--disable-auto-import" +Do not attempt to do sophisticated linking of \f(CW\*(C`_symbol\*(C'\fR to +\&\f(CW\*(C`_\|_imp_\|_symbol\*(C'\fR for DATA imports from DLLs. +[This option is specific to the i386 PE 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, DATA imports from DLL 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 PE 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 DATA imports from DLLs. +[This option is specific to the i386 PE 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 PE 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 PE targeted port of the linker] +.IP "\fB\-\-stack\fR \fIreserve\fR" 4 +.IX Item "--stack reserve" +.PD 0 +.IP "\fB\-\-stack\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4 +.IX Item "--stack reserve,commit" +.PD +Specify the number of bytes 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 PE targeted port of the linker] +.IP "\fB\-\-subsystem\fR \fIwhich\fR" 4 +.IX Item "--subsystem which" +.PD 0 +.IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR" 4 +.IX Item "--subsystem which:major" +.IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR\fB.\fR\fIminor\fR" 4 +.IX Item "--subsystem which:major.minor" +.PD +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, \f(CW\*(C`posix\*(C'\fR, and \f(CW\*(C`xbox\*(C'\fR. You may optionally set +the subsystem version also. Numeric values are also accepted for +\&\fIwhich\fR. +[This option is specific to the i386 PE targeted port of the linker] +.Sp +The following options set flags in the \f(CW\*(C`DllCharacteristics\*(C'\fR field +of the PE file header: +[These options are specific to PE targeted ports of the linker] +.IP \fB\-\-high\-entropy\-va\fR 4 +.IX Item "--high-entropy-va" +.PD 0 +.IP \fB\-\-disable\-high\-entropy\-va\fR 4 +.IX Item "--disable-high-entropy-va" +.PD +Image is compatible with 64\-bit address space layout randomization +(ASLR). This option is enabled by default for 64\-bit PE images. +.Sp +This option also implies \fB\-\-dynamicbase\fR and +\&\fB\-\-enable\-reloc\-section\fR. +.IP \fB\-\-dynamicbase\fR 4 +.IX Item "--dynamicbase" +.PD 0 +.IP \fB\-\-disable\-dynamicbase\fR 4 +.IX Item "--disable-dynamicbase" +.PD +The image base address may be relocated using address space layout +randomization (ASLR). This feature was introduced with MS Windows +Vista for i386 PE targets. This option is enabled by default but +can be disabled via the \fB\-\-disable\-dynamicbase\fR option. +This option also implies \fB\-\-enable\-reloc\-section\fR. +.IP \fB\-\-forceinteg\fR 4 +.IX Item "--forceinteg" +.PD 0 +.IP \fB\-\-disable\-forceinteg\fR 4 +.IX Item "--disable-forceinteg" +.PD +Code integrity checks are enforced. This option is disabled by +default. +.IP \fB\-\-nxcompat\fR 4 +.IX Item "--nxcompat" +.PD 0 +.IP \fB\-\-disable\-nxcompat\fR 4 +.IX Item "--disable-nxcompat" +.PD +The image is compatible with the Data Execution Prevention. +This feature was introduced with MS Windows XP SP2 for i386 PE +targets. The option is enabled by default. +.IP \fB\-\-no\-isolation\fR 4 +.IX Item "--no-isolation" +.PD 0 +.IP \fB\-\-disable\-no\-isolation\fR 4 +.IX Item "--disable-no-isolation" +.PD +Although the image understands isolation, do not isolate the image. +This option is disabled by default. +.IP \fB\-\-no\-seh\fR 4 +.IX Item "--no-seh" +.PD 0 +.IP \fB\-\-disable\-no\-seh\fR 4 +.IX Item "--disable-no-seh" +.PD +The image does not use SEH. No SE handler may be called from +this image. This option is disabled by default. +.IP \fB\-\-no\-bind\fR 4 +.IX Item "--no-bind" +.PD 0 +.IP \fB\-\-disable\-no\-bind\fR 4 +.IX Item "--disable-no-bind" +.PD +Do not bind this image. This option is disabled by default. +.IP \fB\-\-wdmdriver\fR 4 +.IX Item "--wdmdriver" +.PD 0 +.IP \fB\-\-disable\-wdmdriver\fR 4 +.IX Item "--disable-wdmdriver" +.PD +The driver uses the MS Windows Driver Model. This option is disabled +by default. +.IP \fB\-\-tsaware\fR 4 +.IX Item "--tsaware" +.PD 0 +.IP \fB\-\-disable\-tsaware\fR 4 +.IX Item "--disable-tsaware" +.PD +The image is Terminal Server aware. This option is disabled by +default. +.IP \fB\-\-insert\-timestamp\fR 4 +.IX Item "--insert-timestamp" +.PD 0 +.IP \fB\-\-no\-insert\-timestamp\fR 4 +.IX Item "--no-insert-timestamp" +.PD +Insert a real timestamp into the image. This is the default behaviour +as it matches legacy code and it means that the image will work with +other, proprietary tools. The problem with this default is that it +will result in slightly different images being produced each time the +same sources are linked. The option \fB\-\-no\-insert\-timestamp\fR +can be used to insert a zero value for the timestamp, this ensuring +that binaries produced from identical sources will compare +identically. +.IP \fB\-\-enable\-reloc\-section\fR 4 +.IX Item "--enable-reloc-section" +.PD 0 +.IP \fB\-\-disable\-reloc\-section\fR 4 +.IX Item "--disable-reloc-section" +.PD +Create the base relocation table, which is necessary if the image +is loaded at a different image base than specified in the PE header. +This option is enabled by default. +.PP +The C6X uClinux target uses a binary format called DSBT to support shared +libraries. Each shared library in the system needs to have a unique index; +all executables use an index of 0. +.IP "\fB\-\-dsbt\-size\fR \fIsize\fR" 4 +.IX Item "--dsbt-size size" +This option sets the number of entries in the DSBT of the current executable +or shared library to \fIsize\fR. The default is to create a table with 64 +entries. +.IP "\fB\-\-dsbt\-index\fR \fIindex\fR" 4 +.IX Item "--dsbt-index index" +This option sets the DSBT index of the current executable or shared library +to \fIindex\fR. The default is 0, which is appropriate for generating +executables. If a shared library is generated with a DSBT index of 0, the +\&\f(CW\*(C`R_C6000_DSBT_INDEX\*(C'\fR relocs are copied into the output file. +.Sp +The \fB\-\-no\-merge\-exidx\-entries\fR switch disables the merging of adjacent +exidx entries in frame unwind info. +.IP \fB\-\-branch\-stub\fR 4 +.IX Item "--branch-stub" +This option enables linker branch relaxation by inserting branch stub +sections when needed to extend the range of branches. This option is +usually not required since C\-SKY supports branch and call instructions that +can access the full memory range and branch relaxation is normally handled by +the compiler or assembler. +.IP \fB\-\-stub\-group\-size=\fR\fIN\fR 4 +.IX Item "--stub-group-size=N" +This option allows finer control of linker branch stub creation. +It sets the maximum size of a group of input sections that can +be handled by one stub section. A negative value of \fIN\fR locates +stub sections after their branches, while a positive value allows stub +sections to appear either before or after the branches. Values of +\&\fB1\fR or \fB\-1\fR indicate that the +linker should choose suitable defaults. +.PP +The 68HC11 and 68HC12 linkers support specific options to control the +memory bank switching mapping and trampoline code generation. +.IP \fB\-\-no\-trampoline\fR 4 +.IX Item "--no-trampoline" +This option disables the generation of trampoline. By default a trampoline +is generated for each far function which is called using a \f(CW\*(C`jsr\*(C'\fR +instruction (this happens when a pointer to a far function is taken). +.IP "\fB\-\-bank\-window\fR \fIname\fR" 4 +.IX Item "--bank-window name" +This option indicates to the linker the name of the memory region in +the \fBMEMORY\fR specification that describes the memory bank window. +The definition of such region is then used by the linker to compute +paging and addresses within the memory window. +.PP +The following options are supported to control handling of GOT generation +when linking for 68K targets. +.IP \fB\-\-got=\fR\fItype\fR 4 +.IX Item "--got=type" +This option tells the linker which GOT generation scheme to use. +\&\fItype\fR should be one of \fBsingle\fR, \fBnegative\fR, +\&\fBmultigot\fR or \fBtarget\fR. For more information refer to the +Info entry for \fIld\fR. +.PP +The following options are supported to control microMIPS instruction +generation and branch relocation checks for ISA mode transitions when +linking for MIPS targets. +.IP \fB\-\-insn32\fR 4 +.IX Item "--insn32" +.PD 0 +.IP \fB\-\-no\-insn32\fR 4 +.IX Item "--no-insn32" +.PD +These options control the choice of microMIPS instructions used in code +generated by the linker, such as that in the PLT or lazy binding stubs, +or in relaxation. If \fB\-\-insn32\fR is used, then the linker only uses +32\-bit instruction encodings. By default or if \fB\-\-no\-insn32\fR is +used, all instruction encodings are used, including 16\-bit ones where +possible. +.IP \fB\-\-ignore\-branch\-isa\fR 4 +.IX Item "--ignore-branch-isa" +.PD 0 +.IP \fB\-\-no\-ignore\-branch\-isa\fR 4 +.IX Item "--no-ignore-branch-isa" +.PD +These options control branch relocation checks for invalid ISA mode +transitions. If \fB\-\-ignore\-branch\-isa\fR is used, then the linker +accepts any branch relocations and any ISA mode transition required +is lost in relocation calculation, except for some cases of \f(CW\*(C`BAL\*(C'\fR +instructions which meet relaxation conditions and are converted to +equivalent \f(CW\*(C`JALX\*(C'\fR instructions as the associated relocation is +calculated. By default or if \fB\-\-no\-ignore\-branch\-isa\fR is used +a check is made causing the loss of an ISA mode transition to produce +an error. +.IP \fB\-\-compact\-branches\fR 4 +.IX Item "--compact-branches" +.PD 0 +.IP \fB\-\-no\-compact\-branches\fR 4 +.IX Item "--no-compact-branches" +.PD +These options control the generation of compact instructions by the linker +in the PLT entries for MIPS R6. +.PP +For the pdp11\-aout target, three variants of the output format can be +produced as selected by the following options. The default variant +for pdp11\-aout is the \fB\-\-omagic\fR option, whereas for other +targets \fB\-\-nmagic\fR is the default. The \fB\-\-imagic\fR option is +defined only for the pdp11\-aout target, while the others are described +here as they apply to the pdp11\-aout target. +.IP \fB\-N\fR 4 +.IX Item "-N" +.PD 0 +.IP \fB\-\-omagic\fR 4 +.IX Item "--omagic" +.PD +Mark the output as \f(CW\*(C`OMAGIC\*(C'\fR (0407) in the \fIa.out\fR header to +indicate that the text segment is not to be write-protected and +shared. Since the text and data sections are both readable and +writable, the data section is allocated immediately contiguous after +the text segment. This is the oldest format for PDP11 executable +programs and is the default for \fBld\fR on PDP11 Unix systems +from the beginning through 2.11BSD. +.IP \fB\-n\fR 4 +.IX Item "-n" +.PD 0 +.IP \fB\-\-nmagic\fR 4 +.IX Item "--nmagic" +.PD +Mark the output as \f(CW\*(C`NMAGIC\*(C'\fR (0410) in the \fIa.out\fR header to +indicate that when the output file is executed, the text portion will +be read-only and shareable among all processes executing the same +file. This involves moving the data areas up to the first possible 8K +byte page boundary following the end of the text. This option creates +a \fIpure executable\fR format. +.IP \fB\-z\fR 4 +.IX Item "-z" +.PD 0 +.IP \fB\-\-imagic\fR 4 +.IX Item "--imagic" +.PD +Mark the output as \f(CW\*(C`IMAGIC\*(C'\fR (0411) in the \fIa.out\fR header to +indicate that when the output file is executed, the program text and +data areas will be loaded into separate address spaces using the split +instruction and data space feature of the memory management unit in +larger models of the PDP11. This doubles the address space available +to the program. The text segment is again pure, write-protected, and +shareable. The only difference in the output format between this +option and the others, besides the magic number, is that both the text +and data sections start at location 0. The \fB\-z\fR option selected +this format in 2.11BSD. This option creates a \fIseparate +executable\fR format. +.IP \fB\-\-no\-omagic\fR 4 +.IX Item "--no-omagic" +Equivalent to \fB\-\-nmagic\fR for pdp11\-aout. +.SH ENVIRONMENT +.IX Header "ENVIRONMENT" +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 +of the BFD names for an input format. If there is no +\&\f(CW\*(C`GNUTARGET\*(C'\fR in the environment, \fBld\fR uses the natural format +of the target. If \f(CW\*(C`GNUTARGET\*(C'\fR is set to \f(CW\*(C`default\*(C'\fR then BFD +attempts to discover the input format by examining binary input files; +this method often succeeds, but there are potential ambiguities, since +there is no method of ensuring that the magic number used to specify +object-file formats is unique. However, the configuration procedure for +BFD on each system places the conventional format for that system first +in the search-list, so ambiguities are resolved in favor of convention. +.PP +\&\f(CW\*(C`LDEMULATION\*(C'\fR determines the default emulation if you don't use the +\&\fB\-m\fR option. The emulation can affect various aspects of linker +behaviour, particularly the default linker script. You can list the +available emulations with the \fB\-\-verbose\fR or \fB\-V\fR options. If +the \fB\-m\fR option is not used, and the \f(CW\*(C`LDEMULATION\*(C'\fR environment +variable is not defined, the default emulation depends upon how the +linker was configured. +.PP +Normally, the linker will default to demangling symbols. However, if +\&\f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR is set in the environment, then it will +default to not demangling symbols. This environment variable is used in +a similar fashion by the \f(CW\*(C`gcc\*(C'\fR linker wrapper program. The default +may be overridden by the \fB\-\-demangle\fR and \fB\-\-no\-demangle\fR +options. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBar\fR\|(1), \fBnm\fR\|(1), \fBobjcopy\fR\|(1), \fBobjdump\fR\|(1), \fBreadelf\fR\|(1) and +the Info entries for \fIbinutils\fR and +\&\fIld\fR. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 1991\-2023 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +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 "GNU Free Documentation License". |