linker script or the one specified by using @samp{-T}). 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
-@code{INPUT} or @code{GROUP} to load other objects. @xref{Commands}.
+@code{INPUT} or @code{GROUP} 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 @code{SECTIONS} or @code{MEMORY} command, you
+must replace the default linker script using the @samp{-T} option.
+@xref{Commands}.
For options whose names are a single letter,
option arguments must either follow the option letter without intervening
symbols which are used by a dynamic object. This option is needed for
some uses of @code{dlopen}.
-@ifclear SingleFormat
+@kindex -f
+@kindex --auxiliary
+@item -f
+@itemx --auxiliary @var{name}
+When creating an ELF shared object, set the internal DT_AUXILIARY field
+to the specified name. This tells the dynamic linker that the symbol
+table of the shared object should be used as an auxiliary filter on the
+symbol table of the shared object @var{name}.
+
+If you later link a program against this filter object, then, when you
+run the program, the dynamic linker will see the DT_AUXILIARY field. If
+the dynamic linker resolves any symbols from the filter object, it will
+first check whether there is a definition in the shared object
+@var{name}. If there is one, it will be used instead of the definition
+in the filter object. The shared object @var{name} need not exist.
+Thus the shared object @var{name} may be used to provide an alternative
+implementation of certain functions, perhaps for debugging or for
+machine specific performance.
+
@kindex -F
-@item -F
-@itemx -F@var{format}
-Ignored. Some older linkers used this option throughout a compilation
+@kindex --filter
+@item -F @var{name}
+@itemx --filter @var{name}
+When creating an ELF shared object, set the internal DT_FILTER field to
+the specified name. This tells the dynamic linker that the symbol table
+of the shared object which is being created should be used as a filter
+on the symbol table of the shared object @var{name}.
+
+If you later link a program against this filter object, then, when you
+run the program, the dynamic linker will see the DT_FILTER field. The
+dynamic linker will resolve symbols according to the symbol table of the
+filter object as usual, but it will actually link to the definitions
+found in the shared object @var{name}. Thus the filter object can be
+used to select a subset of the symbols provided by the object
+@var{name}.
+
+Some older linkers used the @code{-F} option throughout a compilation
toolchain for specifying object-file format for both input and output
-object files. The mechanisms @code{ld} uses for this purpose (the
-@samp{-b} or @samp{--format} options for input files, @samp{--oformat}
-option or the @code{TARGET} command in linker scripts for output files,
-the @code{GNUTARGET} environment variable) are more flexible, but
-@code{ld} accepts the @samp{-F} option for compatibility with scripts
-written to call the old linker.
-@end ifclear
+object files. The @sc{gnu} linker uses other mechanisms for this
+purpose: the @code{-b}, @code{--format}, @code{--oformat} options, the
+@code{TARGET} command in linker scripts, and the @code{GNUTARGET}
+environment variable. The @sc{gnu} linker will ignore the @code{-F}
+option when not creating an ELF shared object.
@kindex --force-exe-suffix
@item --force-exe-suffix
@item -T @var{commandfile}
@itemx --script=@var{commandfile}
Read link commands from the file @var{commandfile}. These commands
-replace @code{ld}'s default link script (rather than adding
-to it), so @var{commandfile} must specify everything necessary to describe
-the target format. @xref{Commands}. If @var{commandfile} does not
-exist, @code{ld} looks for it in the directories specified by any
-preceding @samp{-L} options. Multiple @samp{-T} options accumulate.
+replace @code{ld}'s default link script (rather than adding to it), so
+@var{commandfile} must specify everything necessary to describe the
+target format. You must use this option if you want to use a command
+which can only appear once in a linker script, such as the
+@code{SECTIONS} or @code{MEMORY} command. @xref{Commands}. If
+@var{commandfile} does not exist, @code{ld} looks for it in the
+directories specified by any preceding @samp{-L} options. Multiple
+@samp{-T} options accumulate.
@kindex -u @var{symbol}
@kindex --undefined=@var{symbol}
placement of common blocks
@end itemize
-You may supply a command file (also known as a link script) to the
+You may supply a command file (also known as a linker script) to the
linker either explicitly through the @samp{-T} option, or implicitly as
-an ordinary file. If the linker opens a file which it cannot recognize
-as a supported object or archive format, it reports an error.
+an ordinary file. Normally you should use the @samp{-T} option. An
+implicit linker script should only be used when you want to augment,
+rather than replace, the default linker script; typically an implicit
+linker script would consist only of @code{INPUT} or @code{GROUP}
+commands.
+
+If the linker opens a file which it cannot recognize as a supported
+object or archive format, nor as a linker script, it reports an error.
@menu
* Scripts:: Linker Scripts
@end ifinfo
@tex
\vskip \baselineskip
-%"lispnarrowing" is the extra indent used generally for @smallexample
+%"lispnarrowing" is the extra indent used generally for smallexample
\hskip\lispnarrowing\vbox{\offinterlineskip
\hrule
\halign
a patch is all we need. We might see problems with your patch and decide
to fix the problem another way, or we might not understand it at all.
-Sometimes with a program as complicated as @code{@value{AS}} it is very hard to
-construct an example that will make the program follow a certain path through
-the code. If you do not send us the example, we will not be able to construct
-one, so we will not be able to verify that the bug is fixed.
+Sometimes with a program as complicated as @code{ld} it is very hard to
+construct an example that will make the program follow a certain path
+through the code. If you do not send us the example, we will not be
+able to construct one, so we will not be able to verify that the bug is
+fixed.
And if we cannot understand what bug you are trying to fix, or why your
patch should be an improvement, we will not install it. A test case will
projects / deliverable / binutils-gdb.git / blobdiff