| .\" Automatically generated by Pod::Man version 1.02 |
| .\" Tue May 22 15:43:56 2001 |
| .\" |
| .\" Standard preamble: |
| .\" ====================================================================== |
| .de Sh \" Subsection heading |
| .br |
| .if t .Sp |
| .ne 5 |
| .PP |
| \fB\\$1\fR |
| .PP |
| .. |
| .de Sp \" Vertical space (when we can't use .PP) |
| .if t .sp .5v |
| .if n .sp |
| .. |
| .de Ip \" List item |
| .br |
| .ie \\n(.$>=3 .ne \\$3 |
| .el .ne 3 |
| .IP "\\$1" \\$2 |
| .. |
| .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. | will give a |
| .\" real vertical bar. \*(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-|\(bv\*(Tr |
| .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\} |
| .\" |
| .\" If the F register is turned on, we'll generate index entries on stderr |
| .\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and |
| .\" index entries marked with X<> in POD. Of course, you'll have to process |
| .\" the output yourself in some meaningful fashion. |
| .if \nF \{\ |
| . de IX |
| . tm Index:\\$1\t\\n%\t"\\$2" |
| . . |
| . nr % 0 |
| . rr F |
| .\} |
| .\" |
| .\" For nroff, turn off justification. Always turn off hyphenation; it |
| .\" makes way too many mistakes in technical documents. |
| .hy 0 |
| .\" |
| .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
| .\" Fear. Run. Save yourself. No user-serviceable parts. |
| .bd B 3 |
| . \" 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 "binutils-2.11.90" "2001-05-22" "GNU" |
| .UC |
| .SH "NAME" |
| ld \- Using \s-1LD\s0, the \s-1GNU\s0 linker |
| .SH "SYNOPSIS" |
| .IX Header "SYNOPSIS" |
| ld [ options ] objfile... |
| .SH "DESCRIPTION" |
| .IX Header "DESCRIPTION" |
| \&\f(CW\*(C`ld\*(C'\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 \f(CW\*(C`ld\*(C'\fR. |
| .PP |
| \&\f(CW\*(C`ld\*(C'\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 |
| \&\f(CW\*(C`ld\*(C'\fR entry in \f(CW\*(C`info\*(C'\fR, or the manual |
| ld: the \s-1GNU\s0 linker, for full details on the command language and |
| on other aspects of the \s-1GNU\s0 linker. |
| .PP |
| This version of \f(CW\*(C`ld\*(C'\fR uses the general purpose \s-1BFD\s0 libraries |
| to operate on object files. This allows \f(CW\*(C`ld\*(C'\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, |
| \&\f(CW\*(C`ld\*(C'\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 \f(CW\*(C`ld\*(C'\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 \f(CW\*(C`ld\*(C'\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 I<output> /lib/crt0.o hello.o -lc |
| .Ve |
| This tells \f(CW\*(C`ld\*(C'\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 \f(CW\*(C`ld\*(C'\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 can not 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 should only be used to augment the main |
| linker script; if you want to use some command that logically can only |
| appear once, such as the \f(CW\*(C`SECTIONS\*(C'\fR or \f(CW\*(C`MEMORY\*(C'\fR command, you |
| must replace the default linker script using the \fB\-T\fR option. |
| .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 preceeded by two dashes. This is to reduce confusion with the |
| \&\fB\-o\fR option. So for example \fB\-omagic\fR sets the output file |
| 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 |
| (eg \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 |
| 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 "\f(CW\*(C`\-a\f(CIkeyword\f(CW\*(C'\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 "\f(CW\*(C`\-A\f(CIarchitecture\f(CW\*(C'\fR" 4 |
| .IX Item "-Aarchitecture" |
| .Ip "\f(CW\*(C`\-\-architecture=\f(CIarchitecture\f(CW\*(C'\fR" 4 |
| .IX Item "--architecture=architecture" |
| In the current release of \f(CW\*(C`ld\*(C'\fR, this option is useful only for the |
| Intel 960 family of architectures. In that \f(CW\*(C`ld\*(C'\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 \f(CW\*(C`ld\*(C'\fR may support similar functionality for |
| other architecture families. |
| .Ip "\f(CW\*(C`\-b \f(CIinput\-format\f(CW\*(C'\fR" 4 |
| .IX Item "-b input-format" |
| .Ip "\f(CW\*(C`\-\-format=\f(CIinput\-format\f(CW\*(C'\fR" 4 |
| .IX Item "--format=input-format" |
| \&\f(CW\*(C`ld\*(C'\fR may be configured to support more than one kind of object |
| file. If your \f(CW\*(C`ld\*(C'\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 \f(CW\*(C`ld\*(C'\fR is |
| configured to support alternative object formats, you don't usually need |
| to specify this, as \f(CW\*(C`ld\*(C'\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 "\f(CW\*(C`\-c \f(CIMRI\-commandfile\f(CW\*(C'\fR" 4 |
| .IX Item "-c MRI-commandfile" |
| .Ip "\f(CW\*(C`\-\-mri\-script=\f(CIMRI\-commandfile\f(CW\*(C'\fR" 4 |
| .IX Item "--mri-script=MRI-commandfile" |
| For compatibility with linkers produced by \s-1MRI\s0, \f(CW\*(C`ld\*(C'\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 \f(CW\*(C`ld\*(C'\fR scripting language. |
| If \fIMRI-cmdfile\fR does not exist, \f(CW\*(C`ld\*(C'\fR looks for it in the directories |
| specified by any \fB\-L\fR options. |
| .Ip "\f(CW\*(C`\-d\*(C'\fR" 4 |
| .IX Item "-d" |
| .Ip "\f(CW\*(C`\-dc\*(C'\fR" 4 |
| .IX Item "-dc" |
| .Ip "\f(CW\*(C`\-dp\*(C'\fR" 4 |
| .IX Item "-dp" |
| 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 "\f(CW\*(C`\-e \f(CIentry\f(CW\*(C'\fR" 4 |
| .IX Item "-e entry" |
| .Ip "\f(CW\*(C`\-\-entry=\f(CIentry\f(CW\*(C'\fR" 4 |
| .IX Item "--entry=entry" |
| 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 "\f(CW\*(C`\-E\*(C'\fR" 4 |
| .IX Item "-E" |
| .Ip "\f(CW\*(C`\-\-export\-dynamic\*(C'\fR" 4 |
| .IX Item "--export-dynamic" |
| 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. |
| .Ip "\f(CW\*(C`\-EB\*(C'\fR" 4 |
| .IX Item "-EB" |
| Link big-endian objects. This affects the default output format. |
| .Ip "\f(CW\*(C`\-EL\*(C'\fR" 4 |
| .IX Item "-EL" |
| Link little-endian objects. This affects the default output format. |
| .Ip "\f(CW\*(C`\-f\*(C'\fR" 4 |
| .IX Item "-f" |
| .Ip "\f(CW\*(C`\-\-auxiliary \f(CIname\f(CW\*(C'\fR" 4 |
| .IX Item "--auxiliary name" |
| 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 "\f(CW\*(C`\-F \f(CIname\f(CW\*(C'\fR" 4 |
| .IX Item "-F name" |
| .Ip "\f(CW\*(C`\-\-filter \f(CIname\f(CW\*(C'\fR" 4 |
| .IX Item "--filter name" |
| 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 \f(CW\*(C`\-F\*(C'\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 \f(CW\*(C`\-b\*(C'\fR, \f(CW\*(C`\-\-format\*(C'\fR, \f(CW\*(C`\-\-oformat\*(C'\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 \f(CW\*(C`\-F\*(C'\fR |
| option when not creating an \s-1ELF\s0 shared object. |
| .Ip "\f(CW\*(C`\-fini \f(CIname\f(CW\*(C'\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 "\f(CW\*(C`\-g\*(C'\fR" 4 |
| .IX Item "-g" |
| Ignored. Provided for compatibility with other tools. |
| .Ip "\f(CW\*(C`\-G\f(CIvalue\f(CW\*(C'\fR" 4 |
| .IX Item "-Gvalue" |
| .Ip "\f(CW\*(C`\-\-gpsize=\f(CIvalue\f(CW\*(C'\fR" 4 |
| .IX Item "--gpsize=value" |
| 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 "\f(CW\*(C`\-h\f(CIname\f(CW\*(C'\fR" 4 |
| .IX Item "-hname" |
| .Ip "\f(CW\*(C`\-soname=\f(CIname\f(CW\*(C'\fR" 4 |
| .IX Item "-soname=name" |
| 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 "\f(CW\*(C`\-i\*(C'\fR" 4 |
| .IX Item "-i" |
| Perform an incremental link (same as option \fB\-r\fR). |
| .Ip "\f(CW\*(C`\-init \f(CIname\f(CW\*(C'\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 "\f(CW\*(C`\-l\f(CIarchive\f(CW\*(C'\fR" 4 |
| .IX Item "-larchive" |
| .Ip "\f(CW\*(C`\-\-library=\f(CIarchive\f(CW\*(C'\fR" 4 |
| .IX Item "--library=archive" |
| Add archive file \fIarchive\fR to the list of files to link. This |
| option may be used any number of times. \f(CW\*(C`ld\*(C'\fR will search its |
| path-list for occurrences of \f(CW\*(C`lib\f(CIarchive\f(CW.a\*(C'\fR for every |
| \&\fIarchive\fR specified. |
| .Sp |
| On systems which support shared libraries, \f(CW\*(C`ld\*(C'\fR may also search for |
| libraries with extensions other than \f(CW\*(C`.a\*(C'\fR. Specifically, on \s-1ELF\s0 |
| and SunOS systems, \f(CW\*(C`ld\*(C'\fR will search a directory for a library with |
| an extension of \f(CW\*(C`.so\*(C'\fR before searching for one with an extension of |
| \&\f(CW\*(C`.a\*(C'\fR. By convention, a \f(CW\*(C`.so\*(C'\fR extension indicates a shared |
| library. |
| .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 \fIfile\fR\|(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 \f(CW\*(C`\-(\*(C'\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 \f(CW\*(C`ld\*(C'\fR on \s-1AIX\s0, note that it is different from the |
| behaviour of the \s-1AIX\s0 linker. |
| .Ip "\f(CW\*(C`\-L\f(CIsearchdir\f(CW\*(C'\fR" 4 |
| .IX Item "-Lsearchdir" |
| .Ip "\f(CW\*(C`\-\-library\-path=\f(CIsearchdir\f(CW\*(C'\fR" 4 |
| .IX Item "--library-path=searchdir" |
| Add path \fIsearchdir\fR to the list of paths that \f(CW\*(C`ld\*(C'\fR will search |
| for archive libraries and \f(CW\*(C`ld\*(C'\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 |
| \&\f(CW\*(C`\-L\*(C'\fR options apply to all \f(CW\*(C`\-l\*(C'\fR options, regardless of the |
| order in which the options appear. |
| .Sp |
| The default set of paths searched (without being specified with |
| \&\fB\-L\fR) depends on which emulation mode \f(CW\*(C`ld\*(C'\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 "\f(CW\*(C`\-m\f(CIemulation\f(CW\*(C'\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 "\f(CW\*(C`\-M\*(C'\fR" 4 |
| .IX Item "-M" |
| .Ip "\f(CW\*(C`\-\-print\-map\*(C'\fR" 4 |
| .IX Item "--print-map" |
| 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 and symbols 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. |
| .RE |
| .RS 4 |
| .RE |
| .Ip "\f(CW\*(C`\-n\*(C'\fR" 4 |
| .IX Item "-n" |
| .Ip "\f(CW\*(C`\-\-nmagic\*(C'\fR" 4 |
| .IX Item "--nmagic" |
| Turn off page alignment of sections, and mark the output as |
| \&\f(CW\*(C`NMAGIC\*(C'\fR if possible. |
| .Ip "\f(CW\*(C`\-N\*(C'\fR" 4 |
| .IX Item "-N" |
| .Ip "\f(CW\*(C`\-\-omagic\*(C'\fR" 4 |
| .IX Item "--omagic" |
| Set the text and data sections to be readable and writable. Also, do |
| not page-align the data segment. If the output format supports Unix |
| style magic numbers, mark the output as \f(CW\*(C`OMAGIC\*(C'\fR. |
| .Ip "\f(CW\*(C`\-o \f(CIoutput\f(CW\*(C'\fR" 4 |
| .IX Item "-o output" |
| .Ip "\f(CW\*(C`\-\-output=\f(CIoutput\f(CW\*(C'\fR" 4 |
| .IX Item "--output=output" |
| Use \fIoutput\fR as the name for the program produced by \f(CW\*(C`ld\*(C'\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 "\f(CW\*(C`\-O \f(CIlevel\f(CW\*(C'\fR" 4 |
| .IX Item "-O level" |
| If \fIlevel\fR is a numeric values greater than zero \f(CW\*(C`ld\*(C'\fR optimizes |
| the output. This might take significantly longer and therefore probably |
| should only be enabled for the final binary. |
| .Ip "\f(CW\*(C`\-q\*(C'\fR" 4 |
| .IX Item "-q" |
| .Ip "\f(CW\*(C`\-\-emit\-relocs\*(C'\fR" 4 |
| .IX Item "--emit-relocs" |
| Leave relocation sections and contents in fully linked exececutables. |
| Post link analysis and optimization tools may need this information in |
| order to perform correct modifications of executables. This results |
| in larger executables. |
| .Ip "\f(CW\*(C`\-r\*(C'\fR" 4 |
| .IX Item "-r" |
| .Ip "\f(CW\*(C`\-\-relocateable\*(C'\fR" 4 |
| .IX Item "--relocateable" |
| Generate relocatable output\-\-\-i.e., generate an output file that can in |
| turn serve as input to \f(CW\*(C`ld\*(C'\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 |
| This option does the same thing as \fB\-i\fR. |
| .Ip "\f(CW\*(C`\-R \f(CIfilename\f(CW\*(C'\fR" 4 |
| .IX Item "-R filename" |
| .Ip "\f(CW\*(C`\-\-just\-symbols=\f(CIfilename\f(CW\*(C'\fR" 4 |
| .IX Item "--just-symbols=filename" |
| 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 \f(CW\*(C`\-R\*(C'\fR option is |
| followed by a directory name, rather than a file name, it is treated as |
| the \f(CW\*(C`\-rpath\*(C'\fR option. |
| .Ip "\f(CW\*(C`\-s\*(C'\fR" 4 |
| .IX Item "-s" |
| .Ip "\f(CW\*(C`\-\-strip\-all\*(C'\fR" 4 |
| .IX Item "--strip-all" |
| Omit all symbol information from the output file. |
| .Ip "\f(CW\*(C`\-S\*(C'\fR" 4 |
| .IX Item "-S" |
| .Ip "\f(CW\*(C`\-\-strip\-debug\*(C'\fR" 4 |
| .IX Item "--strip-debug" |
| Omit debugger symbol information (but not all symbols) from the output file. |
| .Ip "\f(CW\*(C`\-t\*(C'\fR" 4 |
| .IX Item "-t" |
| .Ip "\f(CW\*(C`\-\-trace\*(C'\fR" 4 |
| .IX Item "--trace" |
| Print the names of the input files as \f(CW\*(C`ld\*(C'\fR processes them. |
| .Ip "\f(CW\*(C`\-T \f(CIscriptfile\f(CW\*(C'\fR" 4 |
| .IX Item "-T scriptfile" |
| .Ip "\f(CW\*(C`\-\-script=\f(CIscriptfile\f(CW\*(C'\fR" 4 |
| .IX Item "--script=scriptfile" |
| Use \fIscriptfile\fR as the linker script. This script replaces |
| \&\f(CW\*(C`ld\*(C'\fR's default linker script (rather than adding to it), so |
| \&\fIcommandfile\fR must specify everything necessary to describe the |
| output file. You must use this option if you want to use a command |
| which can only appear once in a linker script, such as the |
| \&\f(CW\*(C`SECTIONS\*(C'\fR or \f(CW\*(C`MEMORY\*(C'\fR command. 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 "\f(CW\*(C`\-u \f(CIsymbol\f(CW\*(C'\fR" 4 |
| .IX Item "-u symbol" |
| .Ip "\f(CW\*(C`\-\-undefined=\f(CIsymbol\f(CW\*(C'\fR" 4 |
| .IX Item "--undefined=symbol" |
| 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 "\f(CW\*(C`\-Ur\*(C'\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 \f(CW\*(C`ld\*(C'\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 "\f(CW\*(C`\-\-unique[=\f(CI\s\-1SECTION\s0\f(CW]\*(C'\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 "\f(CW\*(C`\-v\*(C'\fR" 4 |
| .IX Item "-v" |
| .Ip "\f(CW\*(C`\-\-version\*(C'\fR" 4 |
| .IX Item "--version" |
| .Ip "\f(CW\*(C`\-V\*(C'\fR" 4 |
| .IX Item "-V" |
| Display the version number for \f(CW\*(C`ld\*(C'\fR. The \f(CW\*(C`\-V\*(C'\fR option also |
| lists the supported emulations. |
| .Ip "\f(CW\*(C`\-x\*(C'\fR" 4 |
| .IX Item "-x" |
| .Ip "\f(CW\*(C`\-\-discard\-all\*(C'\fR" 4 |
| .IX Item "--discard-all" |
| Delete all local symbols. |
| .Ip "\f(CW\*(C`\-X\*(C'\fR" 4 |
| .IX Item "-X" |
| .Ip "\f(CW\*(C`\-\-discard\-locals\*(C'\fR" 4 |
| .IX Item "--discard-locals" |
| Delete all temporary local symbols. For most targets, this is all local |
| symbols whose names begin with \fBL\fR. |
| .Ip "\f(CW\*(C`\-y \f(CIsymbol\f(CW\*(C'\fR" 4 |
| .IX Item "-y symbol" |
| .Ip "\f(CW\*(C`\-\-trace\-symbol=\f(CIsymbol\f(CW\*(C'\fR" 4 |
| .IX Item "--trace-symbol=symbol" |
| 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 "\f(CW\*(C`\-Y \f(CIpath\f(CW\*(C'\fR" 4 |
| .IX Item "-Y path" |
| Add \fIpath\fR to the default library search path. This option exists |
| for Solaris compatibility. |
| .Ip "\f(CW\*(C`\-z \f(CIkeyword\f(CW\*(C'\fR" 4 |
| .IX Item "-z keyword" |
| The recognized keywords are \f(CW\*(C`initfirst\*(C'\fR, \f(CW\*(C`interpose\*(C'\fR, |
| \&\f(CW\*(C`loadfltr\*(C'\fR, \f(CW\*(C`nodefaultlib\*(C'\fR, \f(CW\*(C`nodelete\*(C'\fR, \f(CW\*(C`nodlopen\*(C'\fR, |
| \&\f(CW\*(C`nodump\*(C'\fR, \f(CW\*(C`now\*(C'\fR and \f(CW\*(C`origin\*(C'\fR. The other keywords are |
| ignored for Solaris compatibility. \f(CW\*(C`initfirst\*(C'\fR marks the object |
| to be initialized first at runtime before any other objects. |
| \&\f(CW\*(C`interpose\*(C'\fR marks the object that its symbol table interposes |
| before all symbols but the primary executable. \f(CW\*(C`loadfltr\*(C'\fR marks |
| the object that its filtees be processed immediately at runtime. |
| \&\f(CW\*(C`nodefaultlib\*(C'\fR marks the object that the search for dependencies |
| of this object will ignore any default library search paths. |
| \&\f(CW\*(C`nodelete\*(C'\fR marks the object shouldn't be unloaded at runtime. |
| \&\f(CW\*(C`nodlopen\*(C'\fR marks the object not available to \f(CW\*(C`dlopen\*(C'\fR. |
| \&\f(CW\*(C`nodump\*(C'\fR marks the object can not be dumped by \f(CW\*(C`dldump\*(C'\fR. |
| \&\f(CW\*(C`now\*(C'\fR marks the object with the non-lazy runtime binding. |
| \&\f(CW\*(C`origin\*(C'\fR marks the object may contain \f(CW$ORIGIN\fR. |
| \&\f(CW\*(C`defs\*(C'\fR disallows undefined symbols. |
| .Ip "\f(CW\*(C`\-( \f(CIarchives\f(CW \-)\*(C'\fR" 4 |
| .IX Item "-( archives -)" |
| .Ip "\f(CW\*(C`\-\-start\-group \f(CIarchives\f(CW \-\-end\-group\*(C'\fR" 4 |
| .IX Item "--start-group archives --end-group" |
| 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 "\f(CW\*(C`\-assert \f(CIkeyword\f(CW\*(C'\fR" 4 |
| .IX Item "-assert keyword" |
| This option is ignored for SunOS compatibility. |
| .Ip "\f(CW\*(C`\-Bdynamic\*(C'\fR" 4 |
| .IX Item "-Bdynamic" |
| .Ip "\f(CW\*(C`\-dy\*(C'\fR" 4 |
| .IX Item "-dy" |
| .Ip "\f(CW\*(C`\-call_shared\*(C'\fR" 4 |
| .IX Item "-call_shared" |
| 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 |
| \&\f(CW\*(C`\-l\*(C'\fR options which follow it. |
| .Ip "\f(CW\*(C`\-Bgroup\*(C'\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. |
| \&\f(CW\*(C`\-\-no\-undefined\*(C'\fR is implied. This option is only meaningful on \s-1ELF\s0 |
| platforms which support shared libraries. |
| .Ip "\f(CW\*(C`\-Bstatic\*(C'\fR" 4 |
| .IX Item "-Bstatic" |
| .Ip "\f(CW\*(C`\-dn\*(C'\fR" 4 |
| .IX Item "-dn" |
| .Ip "\f(CW\*(C`\-non_shared\*(C'\fR" 4 |
| .IX Item "-non_shared" |
| .Ip "\f(CW\*(C`\-static\*(C'\fR" 4 |
| .IX Item "-static" |
| 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 \f(CW\*(C`\-l\*(C'\fR options which follow it. |
| .Ip "\f(CW\*(C`\-Bsymbolic\*(C'\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 "\f(CW\*(C`\-\-check\-sections\*(C'\fR" 4 |
| .IX Item "--check-sections" |
| .Ip "\f(CW\*(C`\-\-no\-check\-sections\*(C'\fR" 4 |
| .IX Item "--no-check-sections" |
| Asks the linker \fInot\fR to check section addresses after they have |
| been assigned to see if there 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 "\f(CW\*(C`\-\-cref\*(C'\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 "\f(CW\*(C`\-\-defsym \f(CIsymbol\f(CW=\f(CIexpression\f(CW\*(C'\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 "\f(CW\*(C`\-\-demangle[=\f(CIstyle\f(CW]\*(C'\fR" 4 |
| .IX Item "--demangle[=style]" |
| .Ip "\f(CW\*(C`\-\-no\-demangle\*(C'\fR" 4 |
| .IX Item "--no-demangle" |
| 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 "\f(CW\*(C`\-\-dynamic\-linker \f(CIfile\f(CW\*(C'\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 "\f(CW\*(C`\-\-embedded\-relocs\*(C'\fR" 4 |
| .IX Item "--embedded-relocs" |
| This option is only meaningful when linking \s-1MIPS\s0 embedded \s-1PIC\s0 code, |
| generated by the \-membedded-pic option to the \s-1GNU\s0 compiler and |
| assembler. It causes the linker to create a table which may be used at |
| runtime to relocate any data which was statically initialized to pointer |
| values. See the code in testsuite/ld-empic for details. |
| .Ip "\f(CW\*(C`\-\-fatal\-warnings\*(C'\fR" 4 |
| .IX Item "--fatal-warnings" |
| Treat all warnings as errors. |
| .Ip "\f(CW\*(C`\-\-force\-exe\-suffix\*(C'\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 "\f(CW\*(C`\-\-no\-gc\-sections\*(C'\fR" 4 |
| .IX Item "--no-gc-sections" |
| .Ip "\f(CW\*(C`\-\-gc\-sections\*(C'\fR" 4 |
| .IX Item "--gc-sections" |
| 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, nor should it be used with dynamic linking. The default |
| behaviour (of not performing this garbage collection) can be restored by |
| specifying \fB\*(--no-gc-sections\fR on the command line. |
| .Ip "\f(CW\*(C`\-\-help\*(C'\fR" 4 |
| .IX Item "--help" |
| Print a summary of the command-line options on the standard output and exit. |
| .Ip "\f(CW\*(C`\-\-target\-help\*(C'\fR" 4 |
| .IX Item "--target-help" |
| Print a summary of all target specific options on the standard output and exit. |
| .Ip "\f(CW\*(C`\-Map \f(CImapfile\f(CW\*(C'\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 "\f(CW\*(C`\-\-no\-keep\-memory\*(C'\fR" 4 |
| .IX Item "--no-keep-memory" |
| \&\f(CW\*(C`ld\*(C'\fR normally optimizes for speed over memory usage by caching the |
| symbol tables of input files in memory. This option tells \f(CW\*(C`ld\*(C'\fR to |
| instead optimize for memory usage, by rereading the symbol tables as |
| necessary. This may be required if \f(CW\*(C`ld\*(C'\fR runs out of memory space |
| while linking a large executable. |
| .Ip "\f(CW\*(C`\-\-no\-undefined\*(C'\fR" 4 |
| .IX Item "--no-undefined" |
| .Ip "\f(CW\*(C`\-z defs\*(C'\fR" 4 |
| .IX Item "-z defs" |
| Normally when creating a non-symbolic shared library, undefined symbols |
| are allowed and left to be resolved by the runtime loader. These options |
| disallows such undefined symbols. |
| .Ip "\f(CW\*(C`\-\-allow\-shlib\-undefined\*(C'\fR" 4 |
| .IX Item "--allow-shlib-undefined" |
| Allow undefined symbols in shared objects even when \-\-no-undefined is |
| set. The net result will be that undefined symbols in regular objects |
| will still trigger an error, but undefined symbols in shared objects |
| will be ignored. The implementation of no_undefined makes the |
| assumption that the runtime linker will choke on undefined symbols. |
| However there is at least one system (BeOS) where undefined symbols in |
| shared libraries is normal since the kernel patches them at load time to |
| select which function is most appropriate for the current architecture. |
| I.E. dynamically select an appropriate memset function. Apparently it |
| is also normal for \s-1HPPA\s0 shared libraries to have undefined symbols. |
| .Ip "\f(CW\*(C`\-\-no\-warn\-mismatch\*(C'\fR" 4 |
| .IX Item "--no-warn-mismatch" |
| Normally \f(CW\*(C`ld\*(C'\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 \f(CW\*(C`ld\*(C'\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 "\f(CW\*(C`\-\-no\-whole\-archive\*(C'\fR" 4 |
| .IX Item "--no-whole-archive" |
| Turn off the effect of the \f(CW\*(C`\-\-whole\-archive\*(C'\fR option for subsequent |
| archive files. |
| .Ip "\f(CW\*(C`\-\-noinhibit\-exec\*(C'\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 "\f(CW\*(C`\-\-oformat \f(CIoutput\-format\f(CW\*(C'\fR" 4 |
| .IX Item "--oformat output-format" |
| \&\f(CW\*(C`ld\*(C'\fR may be configured to support more than one kind of object |
| file. If your \f(CW\*(C`ld\*(C'\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 \f(CW\*(C`ld\*(C'\fR is configured to support alternative |
| object formats, you don't usually need to specify this, as \f(CW\*(C`ld\*(C'\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 "\f(CW\*(C`\-qmagic\*(C'\fR" 4 |
| .IX Item "-qmagic" |
| This option is ignored for Linux compatibility. |
| .Ip "\f(CW\*(C`\-Qy\*(C'\fR" 4 |
| .IX Item "-Qy" |
| This option is ignored for \s-1SVR4\s0 compatibility. |
| .Ip "\f(CW\*(C`\-\-relax\*(C'\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 "\f(CW\*(C`\-\-retain\-symbols\-file \f(CIfilename\f(CW\*(C'\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 "\f(CW\*(C`\-rpath \f(CIdir\f(CW\*(C'\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 \f(CW\*(C`\-rpath\*(C'\fR |
| arguments are concatenated and passed to the runtime linker, which uses |
| them to locate shared objects at runtime. The \f(CW\*(C`\-rpath\*(C'\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 |
| \&\f(CW\*(C`\-rpath\-link\*(C'\fR option. If \f(CW\*(C`\-rpath\*(C'\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 \f(CW\*(C`\-rpath\*(C'\fR option may also be used on SunOS. By default, on |
| SunOS, the linker will form a runtime search patch out of all the |
| \&\f(CW\*(C`\-L\*(C'\fR options it is given. If a \f(CW\*(C`\-rpath\*(C'\fR option is used, the |
| runtime search path will be formed exclusively using the \f(CW\*(C`\-rpath\*(C'\fR |
| options, ignoring the \f(CW\*(C`\-L\*(C'\fR options. This can be useful when using |
| gcc, which adds many \f(CW\*(C`\-L\*(C'\fR options which may be on \s-1NFS\s0 mounted |
| filesystems. |
| .Sp |
| For compatibility with other \s-1ELF\s0 linkers, if the \f(CW\*(C`\-R\*(C'\fR option is |
| followed by a directory name, rather than a file name, it is treated as |
| the \f(CW\*(C`\-rpath\*(C'\fR option. |
| .Ip "\f(CW\*(C`\-rpath\-link \f(CI\s\-1DIR\s0\f(CW\*(C'\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 \f(CW\*(C`\-rpath\-link\*(C'\fR option |
| specifies the first set of directories to search. The |
| \&\f(CW\*(C`\-rpath\-link\*(C'\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 \f(CW\*(C`\-rpath\-link\*(C'\fR options. |
| .Ip "2." 4 |
| Any directories specified by \f(CW\*(C`\-rpath\*(C'\fR options. The difference |
| between \f(CW\*(C`\-rpath\*(C'\fR and \f(CW\*(C`\-rpath\-link\*(C'\fR is that directories |
| specified by \f(CW\*(C`\-rpath\*(C'\fR options are included in the executable and |
| used at runtime, whereas the \f(CW\*(C`\-rpath\-link\*(C'\fR option is only effective |
| at link time. It is for the native linker only. |
| .Ip "3." 4 |
| On an \s-1ELF\s0 system, if the \f(CW\*(C`\-rpath\*(C'\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 \f(CW\*(C`\-rpath\*(C'\fR option was not used, search any |
| directories specified using \f(CW\*(C`\-L\*(C'\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 "\f(CW\*(C`\-shared\*(C'\fR" 4 |
| .IX Item "-shared" |
| .Ip "\f(CW\*(C`\-Bshareable\*(C'\fR" 4 |
| .IX Item "-Bshareable" |
| 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 \f(CW\*(C`\-e\*(C'\fR option is not used and there are |
| undefined symbols in the link. |
| .Ip "\f(CW\*(C`\-\-sort\-common\*(C'\fR" 4 |
| .IX Item "--sort-common" |
| This option tells \f(CW\*(C`ld\*(C'\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 bytes, then all the four bytes, and then |
| everything else. This is to prevent gaps between symbols due to |
| alignment constraints. |
| .Ip "\f(CW\*(C`\-\-split\-by\-file [\f(CIsize\f(CW]\*(C'\fR" 4 |
| .IX Item "--split-by-file [size]" |
| Similar to \f(CW\*(C`\-\-split\-by\-reloc\*(C'\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 "\f(CW\*(C`\-\-split\-by\-reloc [\f(CIcount\f(CW]\*(C'\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 "\f(CW\*(C`\-\-stats\*(C'\fR" 4 |
| .IX Item "--stats" |
| Compute and display statistics about the operation of the linker, such |
| as execution time and memory usage. |
| .Ip "\f(CW\*(C`\-\-traditional\-format\*(C'\fR" 4 |
| .IX Item "--traditional-format" |
| For some targets, the output of \f(CW\*(C`ld\*(C'\fR is different in some ways from |
| the output of some existing linker. This switch requests \f(CW\*(C`ld\*(C'\fR to |
| use the traditional format instead. |
| .Sp |
| For example, on SunOS, \f(CW\*(C`ld\*(C'\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 \f(CW\*(C`ld\*(C'\fR to not |
| combine duplicate entries. |
| .Ip "\f(CW\*(C`\-\-section\-start \f(CIsectionname\f(CW=\f(CIorg\f(CW\*(C'\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 "\f(CW\*(C`\-Tbss \f(CIorg\f(CW\*(C'\fR" 4 |
| .IX Item "-Tbss org" |
| .Ip "\f(CW\*(C`\-Tdata \f(CIorg\f(CW\*(C'\fR" 4 |
| .IX Item "-Tdata org" |
| .Ip "\f(CW\*(C`\-Ttext \f(CIorg\f(CW\*(C'\fR" 4 |
| .IX Item "-Ttext org" |
| Use \fIorg\fR as the starting address for\-\-\-respectively\-\-\-the |
| \&\f(CW\*(C`bss\*(C'\fR, \f(CW\*(C`data\*(C'\fR, or the \f(CW\*(C`text\*(C'\fR segment of the output file. |
| \&\fIorg\fR must be a single hexadecimal integer; |
| for compatibility with other linkers, you may omit the leading |
| \&\fB0x\fR usually associated with hexadecimal values. |
| .Ip "\f(CW\*(C`\-\-dll\-verbose\*(C'\fR" 4 |
| .IX Item "--dll-verbose" |
| .Ip "\f(CW\*(C`\-\-verbose\*(C'\fR" 4 |
| .IX Item "--verbose" |
| Display the version number for \f(CW\*(C`ld\*(C'\fR and list the linker emulations |
| supported. Display which input files can and cannot be opened. Display |
| the linker script if using a default builtin script. |
| .Ip "\f(CW\*(C`\-\-version\-script=\f(CIversion\-scriptfile\f(CW\*(C'\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 heirarchy for the library being created. This option |
| is only meaningful on \s-1ELF\s0 platforms which support shared libraries. |
| .Ip "\f(CW\*(C`\-\-warn\-common\*(C'\fR" 4 |
| .IX Item "--warn-common" |
| Warn when a common symbol is combined with another common symbol or with |
| a symbol definition. Unix linkers allow this somewhat sloppy practice, |
| but linkers on some other operating systems do not. This option allows |
| you to find potential problems from combining global symbols. |
| Unfortunately, some C libraries use this practice, so you may get some |
| warnings about symbols in the libraries as well as in your programs. |
| .Sp |
| There are three kinds of global symbols, illustrated here by C examples: |
| .RS 4 |
| .Ip "\fBint i = 1;\fR" 4 |
| .IX Item "int i = 1;" |
| A definition, which goes in the initialized data section of the output |
| file. |
| .Ip "\fBextern int i;\fR" 4 |
| .IX Item "extern int i;" |
| An undefined reference, which does not allocate space. |
| There must be either a definition or a common symbol for the |
| variable somewhere. |
| .Ip "\fBint i;\fR" 4 |
| .IX Item "int i;" |
| A common symbol. If there are only (one or more) common symbols for a |
| variable, it goes in the uninitialized data area of the output file. |
| The linker merges multiple common symbols for the same variable into a |
| single symbol. If they are of different sizes, it picks the largest |
| size. The linker turns a common symbol into a declaration, if there is |
| a definition of the same variable. |
| .RE |
| .RS 4 |
| .Sp |
| The \fB\*(--warn-common\fR option can produce five kinds of warnings. |
| Each warning consists of a pair of lines: the first describes the symbol |
| just encountered, and the second describes the previous symbol |
| encountered with the same name. One or both of the two symbols will be |
| a common symbol. |
| .RS 4 |
| .RE |
| .Ip "1." 4 |
| Turning a common symbol into a reference, because there is already a |
| definition for the symbol. |
| .Sp |
| .Vb 3 |
| \& I<file>(I<section>): warning: common of `I<symbol>' |
| \& overridden by definition |
| \& I<file>(I<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 |
| \& I<file>(I<section>): warning: definition of `I<symbol>' |
| \& overriding common |
| \& I<file>(I<section>): warning: common is here |
| .Ve |
| .Ip "3." 4 |
| Merging a common symbol with a previous same-sized common symbol. |
| .Sp |
| .Vb 3 |
| \& I<file>(I<section>): warning: multiple common |
| \& of `I<symbol>' |
| \& I<file>(I<section>): warning: previous common is here |
| .Ve |
| .Ip "4." 4 |
| Merging a common symbol with a previous larger common symbol. |
| .Sp |
| .Vb 3 |
| \& I<file>(I<section>): warning: common of `I<symbol>' |
| \& overridden by larger common |
| \& I<file>(I<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 |
| \& I<file>(I<section>): warning: common of `I<symbol>' |
| \& overriding smaller common |
| \& I<file>(I<section>): warning: smaller common is here |
| .Ve |
| .RE |
| .RS 4 |
| .RE |
| .Ip "\f(CW\*(C`\-\-warn\-constructors\*(C'\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 "\f(CW\*(C`\-\-warn\-multiple\-gp\*(C'\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 "\f(CW\*(C`\-\-warn\-once\*(C'\fR" 4 |
| .IX Item "--warn-once" |
| Only warn once for each undefined symbol, rather than once per module |
| which refers to it. |
| .Ip "\f(CW\*(C`\-\-warn\-section\-align\*(C'\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 "\f(CW\*(C`\-\-whole\-archive\*(C'\fR" 4 |
| .IX Item "--whole-archive" |
| For each archive mentioned on the command line after the |
| \&\f(CW\*(C`\-\-whole\-archive\*(C'\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 \f(CW\*(C`\-Wl,\-whole\-archive\*(C'\fR. |
| Second, don't forget to use \f(CW\*(C`\-Wl,\-no\-whole\-archive\*(C'\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 "\f(CW\*(C`\-\-wrap \f(CIsymbol\f(CW\*(C'\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 (int c) |
| \& { |
| \& printf ("malloc called with %ld\en", c); |
| \& return __real_malloc (c); |
| \& } |
| .Ve |
| If you link other code with this file using \f(CW\*(C`\-\-wrap malloc\*(C'\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 \f(CW\*(C`\-\-wrap\*(C'\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 "\f(CW\*(C`\-\-enable\-new\-dtags\*(C'\fR" 4 |
| .IX Item "--enable-new-dtags" |
| .Ip "\f(CW\*(C`\-\-disable\-new\-dtags\*(C'\fR" 4 |
| .IX Item "--disable-new-dtags" |
| 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 |
| \&\f(CW\*(C`\-\-enable\-new\-dtags\*(C'\fR, the dynamic tags will be created as needed. |
| If you specify \f(CW\*(C`\-\-disable\-new\-dtags\*(C'\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. |
| .PP |
| The i386 \s-1PE\s0 linker supports the \f(CW\*(C`\-shared\*(C'\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 "\f(CW\*(C`\-\-add\-stdcall\-alias\*(C'\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. |
| .Ip "\f(CW\*(C`\-\-base\-file \f(CIfile\f(CW\*(C'\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. |
| .Ip "\f(CW\*(C`\-\-dll\*(C'\fR" 4 |
| .IX Item "--dll" |
| Create a \s-1DLL\s0 instead of a regular executable. You may also use |
| \&\f(CW\*(C`\-shared\*(C'\fR or specify a \f(CW\*(C`LIBRARY\*(C'\fR in a given \f(CW\*(C`.def\*(C'\fR |
| file. |
| .Ip "\f(CW\*(C`\-\-enable\-stdcall\-fixup\*(C'\fR" 4 |
| .IX Item "--enable-stdcall-fixup" |
| .Ip "\f(CW\*(C`\-\-disable\-stdcall\-fixup\*(C'\fR" 4 |
| .IX Item "--disable-stdcall-fixup" |
| 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 \f(CW\*(C`\-\-enable\-stdcall\-fixup\*(C'\fR, this |
| feature is fully enabled and warnings are not printed. If you specify |
| \&\f(CW\*(C`\-\-disable\-stdcall\-fixup\*(C'\fR, this feature is disabled and such |
| mismatches are considered to be errors. |
| .Ip "\f(CW\*(C`\-\-export\-all\-symbols\*(C'\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, and \f(CW\*(C`impure_ptr\*(C'\fR will not be automatically |
| exported. |
| .Ip "\f(CW\*(C`\-\-exclude\-symbols \f(CIsymbol\f(CW,\f(CIsymbol\f(CW,...\*(C'\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. |
| .Ip "\f(CW\*(C`\-\-file\-alignment\*(C'\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. |
| .Ip "\f(CW\*(C`\-\-heap \f(CIreserve\f(CW\*(C'\fR" 4 |
| .IX Item "--heap reserve" |
| .Ip "\f(CW\*(C`\-\-heap \f(CIreserve\f(CW,\f(CIcommit\f(CW\*(C'\fR" 4 |
| .IX Item "--heap reserve,commit" |
| 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. |
| .Ip "\f(CW\*(C`\-\-image\-base \f(CIvalue\f(CW\*(C'\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. |
| .Ip "\f(CW\*(C`\-\-kill\-at\*(C'\fR" 4 |
| .IX Item "--kill-at" |
| If given, the stdcall suffixes (@\fInn\fR) will be stripped from |
| symbols before they are exported. |
| .Ip "\f(CW\*(C`\-\-major\-image\-version \f(CIvalue\f(CW\*(C'\fR" 4 |
| .IX Item "--major-image-version value" |
| Sets the major number of the \*(L"image version\*(R". Defaults to 1. |
| .Ip "\f(CW\*(C`\-\-major\-os\-version \f(CIvalue\f(CW\*(C'\fR" 4 |
| .IX Item "--major-os-version value" |
| Sets the major number of the \*(L"os version\*(R". Defaults to 4. |
| .Ip "\f(CW\*(C`\-\-major\-subsystem\-version \f(CIvalue\f(CW\*(C'\fR" 4 |
| .IX Item "--major-subsystem-version value" |
| Sets the major number of the \*(L"subsystem version\*(R". Defaults to 4. |
| .Ip "\f(CW\*(C`\-\-minor\-image\-version \f(CIvalue\f(CW\*(C'\fR" 4 |
| .IX Item "--minor-image-version value" |
| Sets the minor number of the \*(L"image version\*(R". Defaults to 0. |
| .Ip "\f(CW\*(C`\-\-minor\-os\-version \f(CIvalue\f(CW\*(C'\fR" 4 |
| .IX Item "--minor-os-version value" |
| Sets the minor number of the \*(L"os version\*(R". Defaults to 0. |
| .Ip "\f(CW\*(C`\-\-minor\-subsystem\-version \f(CIvalue\f(CW\*(C'\fR" 4 |
| .IX Item "--minor-subsystem-version value" |
| Sets the minor number of the \*(L"subsystem version\*(R". Defaults to 0. |
| .Ip "\f(CW\*(C`\-\-output\-def \f(CIfile\f(CW\*(C'\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. |
| .Ip "\f(CW\*(C`\-\-section\-alignment\*(C'\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. |
| .Ip "\f(CW\*(C`\-\-stack \f(CIreserve\f(CW\*(C'\fR" 4 |
| .IX Item "--stack reserve" |
| .Ip "\f(CW\*(C`\-\-stack \f(CIreserve\f(CW,\f(CIcommit\f(CW\*(C'\fR" 4 |
| .IX Item "--stack reserve,commit" |
| Specify the amount of memory to reserve (and optionally commit) to be |
| used as stack for this program. The default is 32Mb reserved, 4K |
| committed. |
| .Ip "\f(CW\*(C`\-\-subsystem \f(CIwhich\f(CW\*(C'\fR" 4 |
| .IX Item "--subsystem which" |
| .Ip "\f(CW\*(C`\-\-subsystem \f(CIwhich\f(CW:\f(CImajor\f(CW\*(C'\fR" 4 |
| .IX Item "--subsystem which:major" |
| .Ip "\f(CW\*(C`\-\-subsystem \f(CIwhich\f(CW:\f(CImajor\f(CW.\f(CIminor\f(CW\*(C'\fR" 4 |
| .IX Item "--subsystem which:major.minor" |
| Specifies the subsystem under which your program will execute. The |
| legal values for \fIwhich\fR are \f(CW\*(C`native\*(C'\fR, \f(CW\*(C`windows\*(C'\fR, |
| \&\f(CW\*(C`console\*(C'\fR, and \f(CW\*(C`posix\*(C'\fR. You may optionally set the |
| subsystem version also. |
| .SH "ENVIRONMENT" |
| .IX Header "ENVIRONMENT" |
| You can change the behavior of \f(CW\*(C`ld\*(C'\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, \f(CW\*(C`ld\*(C'\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 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". |