diff options
Diffstat (limited to 'gnu/usr.bin/binutils/ld/ld.1')
| -rw-r--r-- | gnu/usr.bin/binutils/ld/ld.1 | 2156 |
1 files changed, 2156 insertions, 0 deletions
diff --git a/gnu/usr.bin/binutils/ld/ld.1 b/gnu/usr.bin/binutils/ld/ld.1 new file mode 100644 index 0000000..d1e29b8 --- /dev/null +++ b/gnu/usr.bin/binutils/ld/ld.1 @@ -0,0 +1,2156 @@ +.\" $FreeBSD$ +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" 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 +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'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 turned on, 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. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "LD 1" +.TH LD 1 "2010-10-30" "binutils-2.17.50" "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 \s-1AT&T\s0'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 \s-1GNU\s0 linker. +.PP +This version of \fBld\fR uses the general purpose \s-1BFD\s0 libraries +to operate on object files. This allows \fBld\fR to read, combine, and +write object files in many different formats\-\-\-for example, \s-1COFF\s0 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 \s-1GNU\s0 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 \s-1GNU\s0 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. Note that +specifying a script in this way merely augments the main linker script; +use the \fB\-T\fR option to replace the default linker script entirely. +.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 \s-1NMAGIC\s0 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,\-\-startgroup foo.o bar.o \-Wl,\-\-endgroup +.Ve +.PP +This is important, because otherwise the compiler driver program may +silently drop the linker options, resulting in a bad link. +.PP +Here is a table of the generic command line switches accepted by the \s-1GNU\s0 +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 "-akeyword" +This option is supported for \s-1HP/UX\s0 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\-A\fR\fIarchitecture\fR" 4 +.IX Item "-Aarchitecture" +.PD 0 +.IP "\fB\-\-architecture=\fR\fIarchitecture\fR" 4 +.IX Item "--architecture=architecture" +.PD +In the current release of \fBld\fR, this option is useful only for the +Intel 960 family of architectures. In that \fBld\fR configuration, the +\&\fIarchitecture\fR argument identifies the particular architecture in +the 960 family, enabling some safeguards and modifying the +archive-library search path. +.Sp +Future releases of \fBld\fR may support similar functionality for +other architecture families. +.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 \s-1BFD\s0 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 \s-1MRI\s0, \fBld\fR accepts script +files written in an alternate, restricted command language, described in +the \s-1MRI\s0 Compatible Script Files section of \s-1GNU\s0 ld documentation. +Introduce \s-1MRI\s0 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\-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 \s-1PE\s0 targeted +port of the linker and for \s-1ELF\s0 targeted ports. For i386 \s-1PE\s0, symbols +explicitly listed in a .def file are still exported, regardless of this +option. For \s-1ELF\s0 targeted ports, symbols affected by this option will +be treated as hidden. +.IP "\fB\-E\fR" 4 +.IX Item "-E" +.PD 0 +.IP "\fB\-\-export\-dynamic\fR" 4 +.IX Item "--export-dynamic" +.PD +When creating a dynamically linked executable, 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 this option, 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. +.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" 4 +.IX Item "-f" +.PD 0 +.IP "\fB\-\-auxiliary\fR \fIname\fR" 4 +.IX Item "--auxiliary name" +.PD +When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_AUXILIARY\s0 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 \s-1DT_AUXILIARY\s0 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 \s-1DT_AUXILIARY\s0 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 \s-1ELF\s0 shared object, set the internal \s-1DT_FILTER\s0 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 \s-1DT_FILTER\s0 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 \s-1GNU\s0 linker uses other mechanisms for this purpose: the +\&\fB\-b\fR, \fB\-\-format\fR, \fB\-\-oformat\fR options, the +\&\f(CW\*(C`TARGET\*(C'\fR command in linker scripts, and the \f(CW\*(C`GNUTARGET\*(C'\fR +environment variable. +The \s-1GNU\s0 linker will ignore the \fB\-F\fR option when not +creating an \s-1ELF\s0 shared object. +.IP "\fB\-fini\fR \fIname\fR" 4 +.IX Item "-fini name" +When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the +executable or shared object is unloaded, by setting \s-1DT_FINI\s0 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 "-Gvalue" +.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 \s-1GP\s0 register to +\&\fIsize\fR. This is only meaningful for object file formats such as +\&\s-1MIPS\s0 \s-1ECOFF\s0 which supports 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 "-hname" +.PD 0 +.IP "\fB\-soname=\fR\fIname\fR" 4 +.IX Item "-soname=name" +.PD +When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_SONAME\s0 field to +the specified name. When an executable is linked with a shared object +which has a \s-1DT_SONAME\s0 field, then when the executable is run the dynamic +linker will attempt to load the shared object specified by the \s-1DT_SONAME\s0 +field rather than the 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 \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the +executable or shared object is loaded, by setting \s-1DT_INIT\s0 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 "-lnamespec" +.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:\fIfilename\fI\fR, \fBld\fR +will search the library path for a file called \fIfilename\fR, otherise it +will search the library path for a file called \fIlib\fInamespec\fI.a\fR. +.Sp +On systems which support shared libraries, \fBld\fR may also search for +files other than \fIlib\fInamespec\fI.a\fR. Specifically, on \s-1ELF\s0 +and SunOS systems, \fBld\fR will search a directory for a library +called \fIlib\fInamespec\fI.so\fR before searching for one called +\&\fIlib\fInamespec\fI.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:\fIfilename\fI\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 \s-1AIX\s0, note that it is different from the +behaviour of the \s-1AIX\s0 linker. +.IP "\fB\-L\fR\fIsearchdir\fR" 4 +.IX Item "-Lsearchdir" +.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. +.Sp +If \fIsearchdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced +by the \fIsysroot prefix\fR, a path specified when the linker is configured. +.Sp +The default set of paths searched (without being specified with +\&\fB\-L\fR) depends on which emulation mode \fBld\fR is using, and in +some cases also on how it was configured. +.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 "-memulation" +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\-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. +.RE +.RS 4 +.RE +.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 mark the output as +\&\f(CW\*(C`NMAGIC\*(C'\fR if possible. +.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\-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. +.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 \s-1ELF\s0 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 \s-1ELF\s0 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\-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. +.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), 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. +.IP "\fB\-Ur\fR" 4 +.IX Item "-Ur" +For anything other than \*(C+ programs, 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. When linking \*(C+ programs, \fB\-Ur\fR +\&\fIdoes\fR resolve references to constructors, unlike \fB\-r\fR. +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\-\-unique[=\fR\fI\s-1SECTION\s0\fR\fB]\fR" 4 +.IX Item "--unique[=SECTION]" +Creates a separate output section for every input section matching +\&\fI\s-1SECTION\s0\fR, or if the optional wildcard \fI\s-1SECTION\s0\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. +.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 \s-1ELF\s0 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 "\fBcombreloc\fR" 4 +.IX Item "combreloc" +Combines multiple reloc sections and sorts them to make dynamic symbol +lookup caching possible. +.IP "\fBdefs\fR" 4 +.IX Item "defs" +Disallows undefined symbols in object files. Undefined symbols in +shared libraries are still allowed. +.IP "\fBexecstack\fR" 4 +.IX Item "execstack" +Marks the object as requiring executable stack. +.IP "\fBinitfirst\fR" 4 +.IX Item "initfirst" +This option is only meaningful when building a shared object. +It marks the object so that its runtime initialization will occur +before the runtime initialization of any other objects brought into +the process at the same time. Similarly the runtime finalization of +the object will occur after the runtime finalization of any other +objects. +.IP "\fBinterpose\fR" 4 +.IX Item "interpose" +Marks the object that its symbol table interposes before all symbols +but the primary executable. +.IP "\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" +Marks the object that its filters be processed immediately at +runtime. +.IP "\fBmuldefs\fR" 4 +.IX Item "muldefs" +Allows multiple definitions. +.IP "\fBnocombreloc\fR" 4 +.IX Item "nocombreloc" +Disables multiple reloc sections combining. +.IP "\fBnocopyreloc\fR" 4 +.IX Item "nocopyreloc" +Disables production of copy relocs. +.IP "\fBnodefaultlib\fR" 4 +.IX Item "nodefaultlib" +Marks the object that the search for dependencies of this object will +ignore any default library search paths. +.IP "\fBnodelete\fR" 4 +.IX Item "nodelete" +Marks the object shouldn't be unloaded at runtime. +.IP "\fBnodlopen\fR" 4 +.IX Item "nodlopen" +Marks the object not available to \f(CW\*(C`dlopen\*(C'\fR. +.IP "\fBnodump\fR" 4 +.IX Item "nodump" +Marks the object can not be dumped by \f(CW\*(C`dldump\*(C'\fR. +.IP "\fBnoexecstack\fR" 4 +.IX Item "noexecstack" +Marks the object as not requiring executable stack. +.IP "\fBnorelro\fR" 4 +.IX Item "norelro" +Don't create an \s-1ELF\s0 \f(CW\*(C`PT_GNU_RELRO\*(C'\fR segment header in the object. +.IP "\fBnow\fR" 4 +.IX Item "now" +When generating an executable or shared library, mark it to tell the +dynamic linker to resolve all symbols when the program is started, or +when the shared library is linked to using dlopen, instead of +deferring function call resolution to the point when the function is +first called. +.IP "\fBorigin\fR" 4 +.IX Item "origin" +Marks the object may contain \f(CW$ORIGIN\fR. +.IP "\fBrelro\fR" 4 +.IX Item "relro" +Create an \s-1ELF\s0 \f(CW\*(C`PT_GNU_RELRO\*(C'\fR segment header in the object. +.IP "\fBmax\-page\-size=\fR\fIvalue\fR" 4 +.IX Item "max-page-size=value" +Set the emulation maximum page size to \fIvalue\fR. +.IP "\fBcommon\-page\-size=\fR\fIvalue\fR" 4 +.IX Item "common-page-size=value" +Set the emulation common page size to \fIvalue\fR. +.RE +.RS 4 +.Sp +Other keywords are ignored for Solaris compatibility. +.RE +.IP "\fB\-(\fR \fIarchives\fR \fB\-)\fR" 4 +.IX Item "-( archives -)" +.PD 0 +.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 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 \s-1ELF\s0 \s-1DT_NEEDED\s0 tags for dynamic libraries mentioned +on the command line after the \fB\-\-as\-needed\fR option. Normally, +the linker will add a \s-1DT_NEEDED\s0 tag for each dynamic library mentioned +on the command line, regardless of whether the library is actually +needed. \fB\-\-as\-needed\fR causes \s-1DT_NEEDED\s0 tags to only be emitted +for libraries that satisfy some symbol reference from regular objects +which is undefined at the point that the library was linked. +\&\fB\-\-no\-as\-needed\fR restores the default behaviour. +.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 +This option affects the treatment of dynamic libraries from \s-1ELF\s0 +\&\s-1DT_NEEDED\s0 tags in dynamic libraries mentioned on the command line after +the \fB\-\-no\-add\-needed\fR option. Normally, the linker will add +a \s-1DT_NEEDED\s0 tag for each dynamic library from \s-1DT_NEEDED\s0 tags. +\&\fB\-\-no\-add\-needed\fR causes \s-1DT_NEEDED\s0 tags will never be emitted +for those libraries from \s-1DT_NEEDED\s0 tags. \fB\-\-add\-needed\fR restores +the default behaviour. +.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 \s-1ELF\s0 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 \s-1ELF\s0 +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 \s-1ELF\s0 platforms which support shared +libraries. +.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 \s-1ELF\s0 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 \fB\s-1VERSION\s0\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. +.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. The remaining files contain references to the symbol. +.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\-\-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. +.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 \fB\s-1COLLECT_NO_DEMANGLE\s0\fR +is set. These options may be used to override the default. +.IP "\fB\-\-dynamic\-linker\fR \fIfile\fR" 4 +.IX Item "--dynamic-linker file" +Set the name of the dynamic linker. This is only meaningful when +generating dynamically linked \s-1ELF\s0 executables. The default dynamic +linker is normally correct; don't use this unless you know what you are +doing. +.IP "\fB\-\-fatal\-warnings\fR" 4 +.IX Item "--fatal-warnings" +Treat all warnings as errors. +.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. This option is not compatible +with \fB\-r\fR or \fB\-\-emit\-relocs\fR. The default behaviour (of not +performing this garbage collection) can be restored by specifying +\&\fB\-\-no\-gc\-sections\fR on the command line. +.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\-\-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. +.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. +.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 (the default) or disallows undefined symbols in shared libraries. +This switch is similar to \fB\-\-no\-undefined\fR except that it +determines the behaviour when the undefined symbols are in a +shared library rather than a regular object file. It does not affect +how undefined symbols in regular object files are handled. +.Sp +The reason that \fB\-\-allow\-shlib\-undefined\fR is the default is that +the shared library being specified at link time may not be the same as +the one that is available at load time, so the symbols might actually be +resolvable at load time. Plus there are some systems, (eg BeOS) where +undefined symbols in shared libraries is normal. (The kernel patches +them at load time to select which function is most appropriate +for the current architecture. This is used for example to dynamically +select an appropriate memset function). Apparently it is also normal +for \s-1HPPA\s0 shared libraries to have undefined symbols. +.IP "\fB\-\-no\-undefined\-version\fR" 4 +.IX Item "--no-undefined-version" +Normally when a symbol has an undefined version, the linker will ignore +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 \s-1BFD\s0 libraries. (You can +list the available binary formats with \fBobjdump \-i\fR.) The script +command \f(CW\*(C`OUTPUT_FORMAT\*(C'\fR can also specify the output format, but +this option overrides it. +.IP "\fB\-pie\fR" 4 +.IX Item "-pie" +.PD 0 +.IP "\fB\-\-pic\-executable\fR" 4 +.IX Item "--pic-executable" +.PD +Create a position independent executable. This is currently only supported on +\&\s-1ELF\s0 platforms. Position independent executables are similar to shared +libraries in that they are relocated by the dynamic linker to the virtual +address the \s-1OS\s0 chooses for them (which can vary between invocations). Like +normal dynamically linked executables they can be executed and symbols +defined in the executable cannot be overridden by shared libraries. +.IP "\fB\-qmagic\fR" 4 +.IX Item "-qmagic" +This option is ignored for Linux compatibility. +.IP "\fB\-Qy\fR" 4 +.IX Item "-Qy" +This option is ignored for \s-1SVR4\s0 compatibility. +.IP "\fB\-\-relax\fR" 4 +.IX Item "--relax" +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 global +optimizations that become possible when the linker resolves addressing +in the program, such as relaxing address modes and synthesizing new +instructions in the output object file. +.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 \s-1MN10200\s0 and \s-1MN10300\s0 family of processors. +.Sp +On platforms where this is not supported, \fB\-\-relax\fR is 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 \s-1ELF\s0 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. 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. If \fB\-rpath\fR is not used when linking an +\&\s-1ELF\s0 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 patch 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 \s-1NFS\s0 mounted +file systems. +.Sp +For compatibility with other \s-1ELF\s0 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 \fI\s-1DIR\s0\fR" 4 +.IX Item "-rpath-link DIR" +When using \s-1ELF\s0 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 +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 \s-1ELF\s0 system, if the \fB\-rpath\fR and \f(CW\*(C`rpath\-link\*(C'\fR options +were not used, search the contents of the environment variable +\&\f(CW\*(C`LD_RUN_PATH\*(C'\fR. It is for the native linker only. +.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, the contents of the environment variable +\&\f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR. +.IP "6." 4 +For a native \s-1ELF\s0 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 +The default directories, normally \fI/lib\fR and \fI/usr/lib\fR. +.IP "8." 4 +For a native linker on an \s-1ELF\s0 system, if the file \fI/etc/ld.so.conf\fR +exists, the list of directories found in that file. +.RE +.RS 4 +.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 \s-1ELF\s0, \s-1XCOFF\s0 +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" +This option tells \fBld\fR to sort the common symbols by size when it +places them in the appropriate output sections. First come all the one +byte symbols, then all the two byte, then all the four byte, and then +everything else. This is to prevent gaps between symbols due to +alignment constraints. +.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\-\-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 \s-1COFF\s0 object file format; since \s-1COFF\s0 +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\-\-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 \-\-section\-start, with \f(CW\*(C`.bss\*(C'\fR, \f(CW\*(C`.data\*(C'\fR or +\&\f(CW\*(C`.text\*(C'\fR as the \fIsectionname\fR. +.IP "\fB\-\-unresolved\-symbols=\fR\fImethod\fR" 4 +.IX Item "--unresolved-symbols=method" +Determine how to handle unresolved symbols. There are four possible +values for \fBmethod\fR: +.RS 4 +.IP "\fBignore-all\fR" 4 +.IX Item "ignore-all" +Do not report any unresolved symbols. +.IP "\fBreport-all\fR" 4 +.IX Item "report-all" +Report all unresolved symbols. This is the default. +.IP "\fBignore-in-object-files\fR" 4 +.IX Item "ignore-in-object-files" +Report unresolved symbols that are contained in shared libraries, but +ignore them if they come from regular object files. +.IP "\fBignore-in-shared-libs\fR" 4 +.IX Item "ignore-in-shared-libs" +Report unresolved symbols that come from regular object files, but +ignore them if they come from shared libraries. This can be useful +when creating a dynamic binary and it is known that all the shared +libraries that it should be referencing are included on the linker's +command line. +.RE +.RS 4 +.Sp +The behaviour for shared libraries on their own can also be controlled +by the \fB\-\-[no\-]allow\-shlib\-undefined\fR option. +.Sp +Normally the linker will generate an error message for each reported +unresolved symbol but the option \fB\-\-warn\-unresolved\-symbols\fR +can change this to a warning. +.RE +.IP "\fB\-\-dll\-verbose\fR" 4 +.IX Item "--dll-verbose" +.PD 0 +.IP "\fB\-\-verbose\fR" 4 +.IX Item "--verbose" +.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. +.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 meaningful on \s-1ELF\s0 platforms which support shared libraries. +.IP "\fB\-\-warn\-common\fR" 4 +.IX Item "--warn-common" +Warn when a common symbol is combined with another common symbol or with +a symbol definition. Unix linkers allow this somewhat sloppy practise, +but linkers on some other operating systems do not. This option allows +you to find potential problems from combining global symbols. +Unfortunately, some C libraries use this practise, so you may get some +warnings about symbols in the libraries as well as in your programs. +.Sp +There are three kinds of global symbols, illustrated here by C examples: +.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 \s-1COFF\s0 or \s-1ELF\s0, the linker can not +detect the use of global constructors. +.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\-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\-shared\-textrel\fR" 4 +.IX Item "--warn-shared-textrel" +Warn if the linker adds a \s-1DT_TEXTREL\s0 to a shared object. +.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_\f(CIsymbol\f(CW\*(C'\fR. Any +undefined reference to \f(CW\*(C`_\|_real_\f(CIsymbol\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_\f(CIsymbol\f(CW\*(C'\fR. If it +wishes to call the system function, it should call +\&\f(CW\*(C`_\|_real_\f(CIsymbol\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. +.IP "\fB\-\-eh\-frame\-hdr\fR" 4 +.IX Item "--eh-frame-hdr" +Request creation of \f(CW\*(C`.eh_frame_hdr\*(C'\fR section and \s-1ELF\s0 +\&\f(CW\*(C`PT_GNU_EH_FRAME\*(C'\fR segment header. +.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 \s-1ELF\s0. But the older \s-1ELF\s0 +systems may not understand them. If you specify +\&\fB\-\-enable\-new\-dtags\fR, the dynamic tags will be created as needed. +If you specify \fB\-\-disable\-new\-dtags\fR, no new dynamic tags will be +created. By default, the new dynamic tags are not created. Note that +those options are only available for \s-1ELF\s0 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 \s-1ELF\s0 \f(CW\*(C`.hash\*(C'\fR section, \f(CW\*(C`gnu\*(C'\fR for +new style \s-1GNU\s0 \f(CW\*(C`.gnu.hash\*(C'\fR section or \f(CW\*(C`both\*(C'\fR for both +the classic \s-1ELF\s0 \f(CW\*(C`.hash\*(C'\fR and new style \s-1GNU\s0 \f(CW\*(C`.gnu.hash\*(C'\fR +hash tables. The default is \f(CW\*(C`sysv\*(C'\fR. +.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. +.PP +The i386 \s-1PE\s0 linker supports the \fB\-shared\fR option, which causes +the output to be a dynamically linked library (\s-1DLL\s0) 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 \s-1PE\s0 linker +support additional command line options that are specific to the i386 +\&\s-1PE\s0 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 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-base\-file\fR \fIfile\fR" 4 +.IX Item "--base-file file" +Use \fIfile\fR as the name of a file in which to save the base +addresses of all the relocations needed for generating DLLs with +\&\fIdlltool\fR. +[This is an i386 \s-1PE\s0 specific option] +.IP "\fB\-\-dll\fR" 4 +.IX Item "--dll" +Create a \s-1DLL\s0 instead of a regular executable. You may also use +\&\fB\-shared\fR or specify a \f(CW\*(C`LIBRARY\*(C'\fR in a given \f(CW\*(C`.def\*(C'\fR +file. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-enable\-stdcall\-fixup\fR" 4 +.IX Item "--enable-stdcall-fixup" +.PD 0 +.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 \*(L"fuzzy linking\*(R" 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 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-export\-all\-symbols\fR" 4 +.IX Item "--export-all-symbols" +If given, all global symbols in the objects used to build a \s-1DLL\s0 will +be exported by the \s-1DLL\s0. Note that this is the default if there +otherwise wouldn't be any exported symbols. When symbols are +explicitly exported via \s-1DEF\s0 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 \s-1DLL\s0'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 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-exclude\-symbols\fR \fIsymbol\fR\fB,\fR\fIsymbol\fR\fB,...\fR" 4 +.IX Item "--exclude-symbols symbol,symbol,..." +Specifies a list of symbols which should not be automatically +exported. The symbol names may be delimited by commas or colons. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-file\-alignment\fR" 4 +.IX Item "--file-alignment" +Specify the file alignment. Sections in the file will always begin at +file offsets which are multiples of this number. This defaults to +512. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-heap\fR \fIreserve\fR" 4 +.IX Item "--heap reserve" +.PD 0 +.IP "\fB\-\-heap\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4 +.IX Item "--heap reserve,commit" +.PD +Specify the amount of memory to reserve (and optionally commit) to be +used as heap for this program. The default is 1Mb reserved, 4K +committed. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-image\-base\fR \fIvalue\fR" 4 +.IX Item "--image-base value" +Use \fIvalue\fR as the base address of your program or dll. This is +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 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-kill\-at\fR" 4 +.IX Item "--kill-at" +If given, the stdcall suffixes (@\fInn\fR) will be stripped from +symbols before they are exported. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-large\-address\-aware\fR" 4 +.IX Item "--large-address-aware" +If given, the appropriate bit in the \*(L"Characteristics\*(R" field of the \s-1COFF\s0 +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 \*(L"[operating systems]\*(R" +section of the \s-1BOOT\s0.INI. Otherwise, this bit has no effect. +[This option is specific to \s-1PE\s0 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 \*(L"image version\*(R". Defaults to 1. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-major\-os\-version\fR \fIvalue\fR" 4 +.IX Item "--major-os-version value" +Sets the major number of the \*(L"os version\*(R". Defaults to 4. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-major\-subsystem\-version\fR \fIvalue\fR" 4 +.IX Item "--major-subsystem-version value" +Sets the major number of the \*(L"subsystem version\*(R". Defaults to 4. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-minor\-image\-version\fR \fIvalue\fR" 4 +.IX Item "--minor-image-version value" +Sets the minor number of the \*(L"image version\*(R". Defaults to 0. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-minor\-os\-version\fR \fIvalue\fR" 4 +.IX Item "--minor-os-version value" +Sets the minor number of the \*(L"os version\*(R". Defaults to 0. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-minor\-subsystem\-version\fR \fIvalue\fR" 4 +.IX Item "--minor-subsystem-version value" +Sets the minor number of the \*(L"subsystem version\*(R". Defaults to 0. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-output\-def\fR \fIfile\fR" 4 +.IX Item "--output-def file" +The linker will create the file \fIfile\fR which will contain a \s-1DEF\s0 +file corresponding to the \s-1DLL\s0 the linker is generating. This \s-1DEF\s0 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 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-out\-implib\fR \fIfile\fR" 4 +.IX Item "--out-implib file" +The linker will create the file \fIfile\fR which will contain an +import lib corresponding to the \s-1DLL\s0 the linker is generating. This +import lib (which should be called \f(CW\*(C`*.dll.a\*(C'\fR or \f(CW\*(C`*.a\*(C'\fR +may be used to link clients against the generated \s-1DLL\s0; this behaviour +makes it possible to skip a separate \f(CW\*(C`dlltool\*(C'\fR import library +creation step. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-enable\-auto\-image\-base\fR" 4 +.IX Item "--enable-auto-image-base" +Automatically choose the image base for DLLs, unless one is specified +using the \f(CW\*(C`\-\-image\-base\*(C'\fR argument. By using a hash generated +from the dllname to create unique image bases for each \s-1DLL\s0, in-memory +collisions and relocations which can delay program execution are +avoided. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-disable\-auto\-image\-base\fR" 4 +.IX Item "--disable-auto-image-base" +Do not automatically generate a unique image base. If there is no +user-specified image base (\f(CW\*(C`\-\-image\-base\*(C'\fR) then use the platform +default. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-dll\-search\-prefix\fR \fIstring\fR" 4 +.IX Item "--dll-search-prefix string" +When linking dynamically to a dll without an import library, +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 \*(L"subplatforms\*(R": native, cygwin, +uwin, pw, etc. For instance, cygwin DLLs typically use +\&\f(CW\*(C`\-\-dll\-search\-prefix=cyg\*(C'\fR. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-enable\-auto\-import\fR" 4 +.IX Item "--enable-auto-import" +Do sophisticated linking of \f(CW\*(C`_symbol\*(C'\fR to \f(CW\*(C`_\|_imp_\|_symbol\*(C'\fR for +\&\s-1DATA\s0 imports from DLLs, and create the necessary thunking symbols when +building the import libraries with those \s-1DATA\s0 exports. Note: Use of the +\&'auto\-import' extension will cause the text section of the image file +to be made writable. This does not conform to the PE-COFF format +specification published by Microsoft. +.Sp +Using 'auto\-import' generally will 'just work' \*(-- but sometimes you may +see this message: +.Sp +"variable '<var>' can't be auto-imported. Please read the +documentation for ld's \f(CW\*(C`\-\-enable\-auto\-import\*(C'\fR for details." +.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 \s-1DLL\s0, as well as using a +constant index into an array variable imported from a \s-1DLL\s0. 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 practise that +requires using compile-time #defines to indicate whether you are +building a \s-1DLL\s0, building client code that will link to the \s-1DLL\s0, or +merely building/linking to a static library. In making the choice +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. \fIset_foo()\fR and \fIget_foo()\fR accessor +functions). +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-disable\-auto\-import\fR" 4 +.IX Item "--disable-auto-import" +Do not attempt to do sophisticated linking of \f(CW\*(C`_symbol\*(C'\fR to +\&\f(CW\*(C`_\|_imp_\|_symbol\*(C'\fR for \s-1DATA\s0 imports from DLLs. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-enable\-runtime\-pseudo\-reloc\fR" 4 +.IX Item "--enable-runtime-pseudo-reloc" +If your code contains expressions described in \-\-enable\-auto\-import section, +that is, \s-1DATA\s0 imports from \s-1DLL\s0 with non-zero offset, this switch will create +a vector of 'runtime pseudo relocations' which can be used by runtime +environment to adjust references to such data in your client code. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-disable\-runtime\-pseudo\-reloc\fR" 4 +.IX Item "--disable-runtime-pseudo-reloc" +Do not create pseudo relocations for non-zero offset \s-1DATA\s0 imports from +DLLs. This is the default. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-enable\-extra\-pe\-debug\fR" 4 +.IX Item "--enable-extra-pe-debug" +Show additional debug info related to auto-import symbol thunking. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-section\-alignment\fR" 4 +.IX Item "--section-alignment" +Sets the section alignment. Sections in memory will always begin at +addresses which are a multiple of this number. Defaults to 0x1000. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-stack\fR \fIreserve\fR" 4 +.IX Item "--stack reserve" +.PD 0 +.IP "\fB\-\-stack\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4 +.IX Item "--stack reserve,commit" +.PD +Specify the amount of memory to reserve (and optionally commit) to be +used as stack for this program. The default is 2Mb reserved, 4K +committed. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-subsystem\fR \fIwhich\fR" 4 +.IX Item "--subsystem which" +.PD 0 +.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 \s-1PE\s0 targeted port of the linker] +.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 \fB\s-1MEMORY\s0\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. +.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 \s-1BFD\s0 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 \s-1BFD\s0 +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 +\&\s-1BFD\s0 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" +\&\fIar\fR\|(1), \fInm\fR\|(1), \fIobjcopy\fR\|(1), \fIobjdump\fR\|(1), \fIreadelf\fR\|(1) and +the Info entries for \fIbinutils\fR and +\&\fIld\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, +2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation; +with no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. A copy of the license is included in the +section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R". |
