diff options
Diffstat (limited to 'ld')
| -rw-r--r-- | ld/ChangeLog | 8 | ||||
| -rw-r--r-- | ld/Makefile.am | 15 | ||||
| -rw-r--r-- | ld/Makefile.in | 17 | ||||
| -rw-r--r-- | ld/ld.1 | 1437 |
4 files changed, 25 insertions, 1452 deletions
diff --git a/ld/ChangeLog b/ld/ChangeLog index a12c2d8690..b2c5299bff 100644 --- a/ld/ChangeLog +++ b/ld/ChangeLog @@ -1,3 +1,11 @@ +2001-06-18 H.J. Lu <hjl@gnu.org> + + * Makefile.am (ld.1): Remove the prefix `$(srcdir)/'. + (diststuff): Add $(MANS). + * Makefile.in: Regenerated. + + * ld.1: Removed. + 2001-06-18 Hans-Peter Nilsson <hp@axis.com> * emultempl/elf32.em (gld${EMULATION_NAME}_before_allocation): diff --git a/ld/Makefile.am b/ld/Makefile.am index 49b2375a0d..27c5963485 100644 --- a/ld/Makefile.am +++ b/ld/Makefile.am @@ -934,13 +934,14 @@ ld.dvi: $(srcdir)/ld.texinfo configdoc.texi ldver.texi # Build the man page from the texinfo file # The sed command removes the no-adjust Nroff command so that # the man output looks standard. -$(srcdir)/ld.1: $(srcdir)/ld.texinfo - touch $(srcdir)/ld.1 +ld.1: $(srcdir)/ld.texinfo + touch $@ -$(TEXI2POD) $(MANCONF) < $(srcdir)/ld.texinfo > ld.pod -($(POD2MAN) ld.pod | \ - sed -e '/^.if n .na/d' > $(srcdir)/ld.1.T$$$$ && \ - mv -f $(srcdir)/ld.1.T$$$$ $(srcdir)/ld.1) || \ - (rm -f $(srcdir)/ld.1.T$$$$ && exit 1) + sed -e '/^.if n .na/d' > $@.T$$$$ && \ + mv -f $@.T$$$$ $@) || \ + (rm -f $@.T$$$$ && exit 1) + rm -f ld.pod MAINTAINERCLEANFILES = ldver.texi @@ -979,8 +980,8 @@ install-data-local: # Stuff that should be included in a distribution. The diststuff # target is run by the taz target in ../Makefile.in. -LDDISTSTUFF = ldgram.c ldgram.h ldlex.c -diststuff: $(LDDISTSTUFF) info +EXTRA_DIST = ldgram.c ldgram.h ldlex.c $(man_MANS) +diststuff: info $(EXTRA_DIST) DISTCLEANFILES = tdirs site.exp site.bak stringify.sed distclean-local: diff --git a/ld/Makefile.in b/ld/Makefile.in index 22fc273062..fdef9309ee 100644 --- a/ld/Makefile.in +++ b/ld/Makefile.in @@ -431,7 +431,7 @@ CLEANFILES = dep.sed DEP DEPA DEP1 DEP2 # Stuff that should be included in a distribution. The diststuff # target is run by the taz target in ../Makefile.in. -LDDISTSTUFF = ldgram.c ldgram.h ldlex.c +EXTRA_DIST = ldgram.c ldgram.h ldlex.c $(man_MANS) DISTCLEANFILES = tdirs site.exp site.bak stringify.sed ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 @@ -475,7 +475,7 @@ deffilep.c ldgram.c ldlex.c DISTFILES = $(DIST_COMMON) $(SOURCES) $(HEADERS) $(TEXINFOS) $(EXTRA_DIST) -TAR = tar +TAR = gtar GZIP_ENV = --best SOURCES = $(ld_new_SOURCES) $(EXTRA_ld_new_SOURCES) OBJECTS = $(ld_new_OBJECTS) @@ -1637,13 +1637,14 @@ ld.dvi: $(srcdir)/ld.texinfo configdoc.texi ldver.texi # Build the man page from the texinfo file # The sed command removes the no-adjust Nroff command so that # the man output looks standard. -$(srcdir)/ld.1: $(srcdir)/ld.texinfo - touch $(srcdir)/ld.1 +ld.1: $(srcdir)/ld.texinfo + touch $@ -$(TEXI2POD) $(MANCONF) < $(srcdir)/ld.texinfo > ld.pod -($(POD2MAN) ld.pod | \ - sed -e '/^.if n .na/d' > $(srcdir)/ld.1.T$$$$ && \ - mv -f $(srcdir)/ld.1.T$$$$ $(srcdir)/ld.1) || \ - (rm -f $(srcdir)/ld.1.T$$$$ && exit 1) + sed -e '/^.if n .na/d' > $@.T$$$$ && \ + mv -f $@.T$$$$ $@) || \ + (rm -f $@.T$$$$ && exit 1) + rm -f ld.pod # We want to reconfigure if configure.host or configure.tgt changes. config.status: $(srcdir)/configure $(srcdir)/configure.host $(srcdir)/configure.tgt @@ -1673,7 +1674,7 @@ install-data-local: for f in ldscripts/*; do \ $(INSTALL_DATA) $$f $(scriptdir)/$$f ; \ done -diststuff: $(LDDISTSTUFF) info +diststuff: info $(EXTRA_DIST) distclean-local: rm -rf ldscripts diff --git a/ld/ld.1 b/ld/ld.1 deleted file mode 100644 index 21d243a29a..0000000000 --- a/ld/ld.1 +++ /dev/null @@ -1,1437 +0,0 @@ -.\" 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". |
