a1ab1d2aa3
Add new option Bgroup to longopts. (gld*_parse_args): Handle GROUP_OPTION and recognize -z defs. (gld*_list_options): Add -Bgroup and -z defs. * ld.1: Document -Bgroup and -z defs. * ld.texinfo: Likewise.
1509 lines
47 KiB
Groff
1509 lines
47 KiB
Groff
.\" Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
|
|
.\" 2001 Free Software Foundation, Inc.
|
|
.\" See section COPYING for conditions for redistribution
|
|
.TH ld 1 "" "Free Software Foundation" "GNU Development Tools"
|
|
.de BP
|
|
.sp
|
|
.ti \-.2i
|
|
\(**
|
|
..
|
|
|
|
.SH NAME
|
|
ld \- the GNU linker
|
|
|
|
.SH SYNOPSIS
|
|
.hy 0
|
|
.na
|
|
.TP
|
|
.B ld
|
|
.RB "[\|" \-o "
|
|
.I output\c
|
|
\&\|] \c
|
|
.I objfile\c
|
|
\&.\|.\|.
|
|
.br
|
|
.RB "[\|" \-A\c
|
|
.I architecture\c
|
|
\&\|]
|
|
.RB "[\|" "\-b\ "\c
|
|
.I input-format\c
|
|
\&\|]
|
|
.RB "[\|" \-Bstatic "\|]"
|
|
.RB "[\|" \-Bgroup "\|]"
|
|
.RB "[\|" \-Bdynamic "\|]"
|
|
.RB "[\|" \-Bsymbolic "\|]"
|
|
.RB "[\|" "\-c\ "\c
|
|
.I commandfile\c
|
|
\&\|]
|
|
.RB "[\|" \-\-cref "\|]"
|
|
.RB "[\|" \-d | \-dc | \-dp\c
|
|
\|]
|
|
.br
|
|
.RB "[\|" "\-defsym\ "\c
|
|
.I symbol\c
|
|
\&=\c
|
|
.I expression\c
|
|
\&\|]
|
|
.RB "[\|" \-\-demangle "\|]"
|
|
.RB "[\|" \-\-no\-demangle "\|]"
|
|
.RB "[\|" "\-e\ "\c
|
|
.I entry\c
|
|
\&\|]
|
|
.RB "[\|" \-embedded\-relocs "\|]"
|
|
.RB "[\|" \-E "\|]"
|
|
.RB "[\|" \-export\-dynamic "\|]"
|
|
.RB "[\|" "\-f\ "\c
|
|
.I name\c
|
|
\&\|]
|
|
.RB "[\|" "\-\-auxiliary\ "\c
|
|
.I name\c
|
|
\&\|]
|
|
.RB "[\|" "\-F\ "\c
|
|
.I name\c
|
|
\&\|]
|
|
.RB "[\|" "\-\-filter\ "\c
|
|
.I name\c
|
|
\&\|]
|
|
.RB "[\|" "\-format\ "\c
|
|
.I input-format\c
|
|
\&\|]
|
|
.RB "[\|" \-g "\|]"
|
|
.RB "[\|" \-G
|
|
.I size\c
|
|
\&\|]
|
|
.RB "[\|" "\-h\ "\c
|
|
.I name\c
|
|
\&\|]
|
|
.RB "[\|" "\-soname\ "\c
|
|
.I name\c
|
|
\&\|]
|
|
.RB "[\|" \-\-help "\|]"
|
|
.RB "[\|" \-i "\|]"
|
|
.RB "[\|" \-l\c
|
|
.I ar\c
|
|
\&\|]
|
|
.RB "[\|" \-L\c
|
|
.I searchdir\c
|
|
\&\|]
|
|
.RB "[\|" \-M "\|]"
|
|
.RB "[\|" \-Map
|
|
.I mapfile\c
|
|
\&\|]
|
|
.RB "[\|" \-m
|
|
.I emulation\c
|
|
\&\|]
|
|
.RB "[\|" \-n | \-N "\|]"
|
|
.RB "[\|" \-noinhibit-exec "\|]"
|
|
.RB "[\|" \-no\-keep\-memory "\|]"
|
|
.RB "[\|" \-no\-warn\-mismatch "\|]"
|
|
.RB "[\|" \-O\c
|
|
.I level\c
|
|
\&\|]
|
|
.RB "[\|" "\--oformat\ "\c
|
|
.I output-format\c
|
|
\&\|]
|
|
.RB "[\|" "\-R\ "\c
|
|
.I filename\c
|
|
\&\|]
|
|
.RB "[\|" \-relax "\|]"
|
|
.RB "[\|" \-r | \-Ur "\|]"
|
|
.RB "[\|" "\-rpath\ "\c
|
|
.I directory\c
|
|
\&\|]
|
|
.RB "[\|" "\-rpath\-link\ "\c
|
|
.I directory\c
|
|
\&\|]
|
|
.RB "[\|" \-S "\|]"
|
|
.RB "[\|" \-s "\|]"
|
|
.RB "[\|" \-shared "\|]"
|
|
.RB "[\|" \-sort\-common "\|]"
|
|
.RB "[\|" "\-split\-by\-reloc\ "\c
|
|
.I count\c
|
|
\&\|]
|
|
.RB "[\|" \-split\-by\-file "\|]"
|
|
.RB "[\|" "\-T\ "\c
|
|
.I commandfile\c
|
|
\&\|]
|
|
.RB "[\|" "\-\-section\-start\ "\c
|
|
.I sectionname\c
|
|
\&=\c
|
|
.I sectionorg\c
|
|
\&\|]
|
|
.RB "[\|" "\-Ttext\ "\c
|
|
.I textorg\c
|
|
\&\|]
|
|
.RB "[\|" "\-Tdata\ "\c
|
|
.I dataorg\c
|
|
\&\|]
|
|
.RB "[\|" "\-Tbss\ "\c
|
|
.I bssorg\c
|
|
\&\|]
|
|
.RB "[\|" \-t "\|]"
|
|
.RB "[\|" "\-u\ "\c
|
|
.I sym\c
|
|
\&]
|
|
.RB "[\|" \-V "\|]"
|
|
.RB "[\|" \-v "\|]"
|
|
.RB "[\|" \-\-verbose "\|]"
|
|
.RB "[\|" \-\-version "\|]"
|
|
.RB "[\|" \-warn\-common "\|]"
|
|
.RB "[\|" \-warn\-constructors "\|]"
|
|
.RB "[\|" \-warn\-multiple\-gp "\|]"
|
|
.RB "[\|" \-warn\-once "\|]"
|
|
.RB "[\|" \-warn\-section\-align "\|]"
|
|
.RB "[\|" \-\-whole\-archive "\|]"
|
|
.RB "[\|" \-\-no\-whole\-archive "\|]"
|
|
.RB "[\|" "\-\-wrap\ "\c
|
|
.I symbol\c
|
|
\&\|]
|
|
.RB "[\|" \-X "\|]"
|
|
.RB "[\|" \-x "\|]"
|
|
.ad b
|
|
.hy 1
|
|
.SH DESCRIPTION
|
|
\c
|
|
.B ld\c
|
|
\& combines a number of object and archive files, relocates
|
|
their data and ties up symbol references. Often the last step in
|
|
building a new compiled program to run is a call to \c
|
|
.B ld\c
|
|
\&.
|
|
|
|
\c
|
|
.B ld\c
|
|
\& accepts Linker Command Language files
|
|
to provide explicit and total control over the linking process.
|
|
This man page does not describe the command language; see the `\|\c
|
|
.B ld\c
|
|
\|' entry in `\|\c
|
|
.B info\c
|
|
\|', or the manual
|
|
.I
|
|
ld: the GNU linker
|
|
\&, for full details on the command language and on other aspects of
|
|
the GNU linker.
|
|
|
|
This version of \c
|
|
.B ld\c
|
|
\& uses the general purpose BFD libraries
|
|
to operate on object files. This allows \c
|
|
.B ld\c
|
|
\& to read, combine, and
|
|
write object files in many different formats\(em\&for example, COFF or
|
|
\c
|
|
.B a.out\c
|
|
\&. Different formats may be linked together to produce any
|
|
available kind of object file. You can use `\|\c
|
|
.B objdump \-i\c
|
|
\|' to get a list of formats supported on various architectures; see
|
|
.BR objdump ( 1 ).
|
|
|
|
Aside from its flexibility, the GNU linker is more helpful than other
|
|
linkers in providing diagnostic information. Many linkers abandon
|
|
execution immediately upon encountering an error; whenever possible,
|
|
\c
|
|
.B ld\c
|
|
\& continues executing, allowing you to identify other errors
|
|
(or, in some cases, to get an output file in spite of the error).
|
|
|
|
The GNU linker \c
|
|
.B ld\c
|
|
\& 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 through the command line,
|
|
and through environment variables.
|
|
|
|
.SH OPTIONS
|
|
The plethora of command-line options may seem intimidating, but in
|
|
actual practice few of them are used in any particular context.
|
|
For instance, a frequent use of \c
|
|
.B ld\c
|
|
\& is to link standard Unix
|
|
object files on a standard, supported Unix system. On such a system, to
|
|
link a file \c
|
|
.B hello.o\c
|
|
\&:
|
|
.sp
|
|
.br
|
|
$\ ld\ \-o\ output\ /lib/crt0.o\ hello.o\ \-lc
|
|
.br
|
|
.sp
|
|
This tells \c
|
|
.B ld\c
|
|
\& to produce a file called \c
|
|
.B output\c
|
|
\& as the
|
|
result of linking the file \c
|
|
.B /lib/crt0.o\c
|
|
\& with \c
|
|
.B hello.o\c
|
|
\& and
|
|
the library \c
|
|
.B libc.a\c
|
|
\& which will come from the standard search
|
|
directories.
|
|
|
|
The command-line options to \c
|
|
.B ld\c
|
|
\& may be specified in any order, and
|
|
may be repeated at will. For the most part, repeating an option with a
|
|
different argument will either have no further effect, or override prior
|
|
occurrences (those further to the left on the command line) of an
|
|
option.
|
|
|
|
The exceptions\(em\&which may meaningfully be used more than once\(em\&are
|
|
\c
|
|
.B \-A\c
|
|
\&, \c
|
|
.B \-b\c
|
|
\& (or its synonym \c
|
|
.B \-format\c
|
|
\&), \c
|
|
.B \-defsym\c
|
|
\&, \c
|
|
.B \-\-section\-start\c
|
|
\&, \c
|
|
.B \-L\c
|
|
\&, \c
|
|
.B \-l\c
|
|
\&, \c
|
|
.B \-R\c
|
|
\&, and \c
|
|
.B \-u\c
|
|
\&.
|
|
|
|
The list of object files to be linked together, shown as \c
|
|
.I objfile\c
|
|
\&,
|
|
may follow, precede, or be mixed in with command-line options; save that
|
|
an \c
|
|
.I objfile\c
|
|
\& argument may not be placed between an option flag and
|
|
its argument.
|
|
|
|
Usually the linker is invoked with at least one object file, but other
|
|
forms of binary input files can also be specified with \c
|
|
.B \-l\c
|
|
\&,
|
|
\c
|
|
.B \-R\c
|
|
\&, and the script command language. If \c
|
|
.I no\c
|
|
\& binary input
|
|
files at all are specified, the linker does not produce any output, and
|
|
issues the message `\|\c
|
|
.B No input files\c
|
|
\|'.
|
|
|
|
Option arguments must either follow the option letter without intervening
|
|
whitespace, or be given as separate arguments immediately following the
|
|
option that requires them.
|
|
|
|
.TP
|
|
.BI "-A" "architecture"
|
|
In the current release of \c
|
|
.B ld\c
|
|
\&, this option is useful only for the
|
|
Intel 960 family of architectures. In that \c
|
|
.B ld\c
|
|
\& configuration, the
|
|
\c
|
|
.I architecture\c
|
|
\& argument is one of the two-letter names identifying
|
|
members of the 960 family; the option specifies the desired output
|
|
target, and warns of any incompatible instructions in the input files.
|
|
It also modifies the linker's search strategy for archive libraries, to
|
|
support the use of libraries specific to each particular
|
|
architecture, by including in the search loop names suffixed with the
|
|
string identifying the architecture.
|
|
|
|
For example, if your \c
|
|
.B ld\c
|
|
\& command line included `\|\c
|
|
.B \-ACA\c
|
|
\|' as
|
|
well as `\|\c
|
|
.B \-ltry\c
|
|
\|', the linker would look (in its built-in search
|
|
paths, and in any paths you specify with \c
|
|
.B \-L\c
|
|
\&) for a library with
|
|
the names
|
|
.sp
|
|
.br
|
|
try
|
|
.br
|
|
libtry.a
|
|
.br
|
|
tryca
|
|
.br
|
|
libtryca.a
|
|
.br
|
|
.sp
|
|
|
|
The first two possibilities would be considered in any event; the last
|
|
two are due to the use of `\|\c
|
|
.B \-ACA\c
|
|
\|'.
|
|
|
|
Future releases of \c
|
|
.B ld\c
|
|
\& may support similar functionality for
|
|
other architecture families.
|
|
|
|
You can meaningfully use \c
|
|
.B \-A\c
|
|
\& more than once on a command line, if
|
|
an architecture family allows combination of target architectures; each
|
|
use will add another pair of name variants to search for when \c
|
|
.B \-l
|
|
specifies a library.
|
|
|
|
.TP
|
|
.BI "\-b " "input-format"
|
|
Specify the binary format for input object files that follow this option
|
|
on the command line. You don't usually need to specify this, as
|
|
\c
|
|
.B ld\c
|
|
\& is configured to expect as a default input format the most
|
|
usual format on each machine. \c
|
|
.I input-format\c
|
|
\& is a text string, the
|
|
name of a particular format supported by the BFD libraries.
|
|
\c
|
|
.B \-format \c
|
|
.I input-format\c
|
|
\&\c
|
|
\& has the same effect, as does the script command
|
|
.BR TARGET .
|
|
|
|
You may want to use this option if you are linking files with an unusual
|
|
binary format. You can also use \c
|
|
.B \-b\c
|
|
\& to switch formats explicitly (when
|
|
linking object files of different formats), by including
|
|
\c
|
|
.B \-b \c
|
|
.I input-format\c
|
|
\&\c
|
|
\& before each group of object files in a
|
|
particular format.
|
|
|
|
The default format is taken from the environment variable
|
|
.B GNUTARGET\c
|
|
\&. You can also define the input
|
|
format from a script, using the command \c
|
|
.B TARGET\c
|
|
\&.
|
|
|
|
.TP
|
|
.B \-Bstatic
|
|
Do not link against shared libraries. This is only meaningful on
|
|
platforms for which shared libraries are supported.
|
|
|
|
.TP
|
|
.B \-Bdynamic
|
|
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.
|
|
|
|
.TP
|
|
.B \-Bgroup
|
|
Set the \c
|
|
.B DF_1_GROUP
|
|
\c
|
|
flag in the \c
|
|
.B DT_FLAGS_1
|
|
\c
|
|
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. No undefined symbols are allowed. This option is only
|
|
meaningful on ELF platforms which support shared libraries.
|
|
|
|
.TP
|
|
.B \-Bsymbolic
|
|
When creating a shared library, bind references to global symbols to
|
|
the definition within the shared library, if any. Normally, it is
|
|
possible for a program linked against a shared library to override the
|
|
definition within the shared library. This option is only meaningful
|
|
on ELF platforms which support shared libraries.
|
|
|
|
.TP
|
|
.BI "\-c " "commandfile"
|
|
Directs \c
|
|
.B ld\c
|
|
\& to read link commands from the file
|
|
\c
|
|
.I commandfile\c
|
|
\&. These commands will completely override \c
|
|
.B ld\c
|
|
\&'s
|
|
default link format (rather than adding to it); \c
|
|
.I commandfile\c
|
|
\& must
|
|
specify everything necessary to describe the target format.
|
|
|
|
|
|
You may also include a script of link commands directly in the command
|
|
line by bracketing it between `\|\c
|
|
.B {\c
|
|
\|' and `\|\c
|
|
.B }\c
|
|
\|' characters.
|
|
|
|
.TP
|
|
.B \-\-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.
|
|
|
|
.TP
|
|
.B \-d
|
|
.TP
|
|
.B \-dc
|
|
.TP
|
|
.B \-dp
|
|
These three options are equivalent; multiple forms are supported for
|
|
compatibility with other linkers. Use any of them to make \c
|
|
.B ld
|
|
assign space to common symbols even if a relocatable output file is
|
|
specified (\c
|
|
.B \-r\c
|
|
\&). The script command
|
|
\c
|
|
.B FORCE_COMMON_ALLOCATION\c
|
|
\& has the same effect.
|
|
|
|
.TP
|
|
.BI "-defsym " "symbol" "\fR=\fP" expression
|
|
Create a global symbol in the output file, containing the absolute
|
|
address given by \c
|
|
.I expression\c
|
|
\&. 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 \c
|
|
.I expression\c
|
|
\& in this
|
|
context: you may give a hexadecimal constant or the name of an existing
|
|
symbol, or use \c
|
|
.B +\c
|
|
\& and \c
|
|
.B \-\c
|
|
\& to add or subtract hexadecimal
|
|
constants or symbols. If you need more elaborate expressions, consider
|
|
using the linker command language from a script.
|
|
|
|
.TP
|
|
.B \-\-demangle
|
|
.TP
|
|
.B \-\-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. The linker will
|
|
demangle by default unless the environment variable
|
|
.B COLLECT_NO_DEMANGLE
|
|
is set. These options may be used to override the default.
|
|
|
|
.TP
|
|
.BI "-e " "entry"\c
|
|
\&
|
|
Use \c
|
|
.I entry\c
|
|
\& as the explicit symbol for beginning execution of your
|
|
program, rather than the default entry point. See the `\|\c
|
|
.B ld\c
|
|
\|' entry in `\|\c
|
|
.B info\c
|
|
\|' for a
|
|
discussion of defaults and other ways of specifying the
|
|
entry point.
|
|
|
|
.TP
|
|
.B \-embedded\-relocs
|
|
This option is only meaningful when linking MIPS embedded PIC code,
|
|
generated by the
|
|
.B \-membedded\-pic
|
|
option to the GNU 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.
|
|
|
|
.TP
|
|
.B \-E
|
|
.TP
|
|
.B \-export\-dynamic
|
|
When creating an ELF file, add all symbols to the dynamic symbol table.
|
|
Normally, the dynamic symbol table contains only symbols which are used
|
|
by a dynamic object. This option is needed for some uses of
|
|
.I dlopen.
|
|
|
|
.TP
|
|
.BI "-f " "name"
|
|
.TP
|
|
.BI "--auxiliary " "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
|
|
.I name.
|
|
|
|
.TP
|
|
.BI "-F " "name"
|
|
.TP
|
|
.BI "--filter " "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 should be used as a filter on the symbol table of
|
|
the shared object
|
|
.I name.
|
|
|
|
.TP
|
|
.BI "\-format " "input\-format"
|
|
Synonym for \c
|
|
.B \-b\c
|
|
\& \c
|
|
.I input\-format\c
|
|
\&.
|
|
|
|
.TP
|
|
.B \-g
|
|
Accepted, but ignored; provided for compatibility with other tools.
|
|
|
|
.TP
|
|
.BI "\-G " "size"\c
|
|
Set the maximum size of objects to be optimized using the GP register
|
|
to
|
|
.I size
|
|
under MIPS ECOFF. Ignored for other object file formats.
|
|
|
|
.TP
|
|
.BI "-h " "name"
|
|
.TP
|
|
.BI "-soname " "name"
|
|
When creating an ELF shared object, set the internal DT_SONAME field to
|
|
the specified name. When an executable is linked with a shared object
|
|
which has a DT_SONAME field, then when the executable is run the dynamic
|
|
linker will attempt to load the shared object specified by the DT_SONAME
|
|
field rather than the using the file name given to the linker.
|
|
|
|
.TP
|
|
.B \-\-help
|
|
Print a summary of the command-line options on the standard output and exit.
|
|
This option and
|
|
.B \-\-version
|
|
begin with two dashes instead of one
|
|
for compatibility with other GNU programs. The other options start with
|
|
only one dash for compatibility with other linkers.
|
|
|
|
.TP
|
|
.B \-i
|
|
Perform an incremental link (same as option \c
|
|
.B \-r\c
|
|
\&).
|
|
|
|
.TP
|
|
.BI "\-l" "ar"\c
|
|
\&
|
|
Add an archive file \c
|
|
.I ar\c
|
|
\& to the list of files to link. This
|
|
option may be used any number of times. \c
|
|
.B ld\c
|
|
\& will search its
|
|
path-list for occurrences of \c
|
|
.B lib\c
|
|
.I ar\c
|
|
\&.a\c
|
|
\& for every \c
|
|
.I ar
|
|
specified.
|
|
|
|
.TP
|
|
.BI "\-L" "searchdir"
|
|
This command adds path \c
|
|
.I searchdir\c
|
|
\& to the list of paths that
|
|
\c
|
|
.B ld\c
|
|
\& will search for archive libraries. You may use this option
|
|
any number of times.
|
|
|
|
The default set of paths searched (without being specified with
|
|
\c
|
|
.B \-L\c
|
|
\&) depends on what emulation mode \c
|
|
.B ld\c
|
|
\& is using, and in
|
|
some cases also on how it was configured. The
|
|
paths can also be specified in a link script with the \c
|
|
.B SEARCH_DIR
|
|
command.
|
|
|
|
.TP
|
|
.B \-M
|
|
Print (to the standard output file) a link map\(em\&diagnostic information
|
|
about where symbols are mapped by \c
|
|
.B ld\c
|
|
\&, and information on global
|
|
common storage allocation.
|
|
|
|
.TP
|
|
.BI "\-Map " "mapfile"\c
|
|
Print to the file
|
|
.I mapfile
|
|
a link map\(em\&diagnostic information
|
|
about where symbols are mapped by \c
|
|
.B ld\c
|
|
\&, and information on global
|
|
common storage allocation.
|
|
|
|
.TP
|
|
.BI "\-m " "emulation"\c
|
|
Emulate the
|
|
.I emulation
|
|
linker. You can list the available emulations with the
|
|
.I \-\-verbose
|
|
or
|
|
.I \-V
|
|
options. This option overrides the compiled-in default, which is the
|
|
system for which you configured
|
|
.BR ld .
|
|
|
|
.TP
|
|
.B \-N
|
|
specifies readable and writable \c
|
|
.B text\c
|
|
\& and \c
|
|
.B data\c
|
|
\& sections. If
|
|
the output format supports Unix style magic numbers, the output is
|
|
marked as \c
|
|
.B OMAGIC\c
|
|
\&.
|
|
|
|
When you use the `\|\c
|
|
.B \-N\c
|
|
\&\|' option, the linker does not page-align the
|
|
data segment.
|
|
|
|
.TP
|
|
.B \-n
|
|
sets the text segment to be read only, and \c
|
|
.B NMAGIC\c
|
|
\& is written
|
|
if possible.
|
|
|
|
.TP
|
|
.B \-noinhibit\-exec
|
|
Normally, the linker will not produce an output file if it encounters
|
|
errors during the link process. With this flag, you can specify that
|
|
you wish the output file retained even after non-fatal errors.
|
|
|
|
.TP
|
|
.B \-no\-keep\-memory
|
|
The linker normally optimizes for speed over memory usage by caching
|
|
the symbol tables of input files in memory. This option tells the
|
|
linker to instead optimize for memory usage, by rereading the symbol
|
|
tables as necessary. This may be required if the linker runs out of
|
|
memory space while linking a large executable.
|
|
|
|
.TP
|
|
.B \-no\-warn\-mismatch
|
|
Normally the linker 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 the linker 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.
|
|
|
|
.TP
|
|
.BI "\-o " "output"
|
|
.I output\c
|
|
\& is a name for the program produced by \c
|
|
.B ld\c
|
|
\&; if this
|
|
option is not specified, the name `\|\c
|
|
.B a.out\c
|
|
\|' is used by default. The
|
|
script command \c
|
|
.B OUTPUT\c
|
|
\& can also specify the output file name.
|
|
|
|
.TP
|
|
.BI "\-O" "level"
|
|
Generate optimized output files. This might use significantly more
|
|
time and therefore probably should be enabled only for generating the
|
|
final binary.
|
|
\c
|
|
.I level\c
|
|
\& is supposed to be a numeric value. Any value greater than zero enables
|
|
the optimizations.
|
|
|
|
.TP
|
|
.BI "\--oformat " "output\-format"
|
|
Specify the binary format for the output object file.
|
|
You don't usually need to specify this, as
|
|
\c
|
|
.B ld\c
|
|
\& is configured to produce as a default output format the most
|
|
usual format on each machine. \c
|
|
.I output-format\c
|
|
\& is a text string, the
|
|
name of a particular format supported by the BFD libraries.
|
|
The script command
|
|
.B OUTPUT_FORMAT
|
|
can also specify the output format, but this option overrides it.
|
|
|
|
.TP
|
|
.BI "\-R " "filename"
|
|
Read symbol names and their addresses from \c
|
|
.I filename\c
|
|
\&, 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.
|
|
|
|
.TP
|
|
.B \-relax
|
|
An option with machine dependent effects. Currently this option is only
|
|
supported on the H8/300.
|
|
|
|
On some platforms, use this option to perform global optimizations that
|
|
become possible when the linker resolves addressing in your program, such
|
|
as relaxing address modes and synthesizing new instructions in the
|
|
output object file.
|
|
|
|
On platforms where this is not supported, `\|\c
|
|
.B \-relax\c
|
|
\&\|' is accepted, but has no effect.
|
|
|
|
.TP
|
|
.B \-r
|
|
Generates relocatable output\(em\&i.e., generate an output file that can in
|
|
turn serve as input to \c
|
|
.B ld\c
|
|
\&. This is often called \c
|
|
.I partial
|
|
linking\c
|
|
\&. As a side effect, in environments that support standard Unix
|
|
magic numbers, this option also sets the output file's magic number to
|
|
\c
|
|
.B OMAGIC\c
|
|
\&.
|
|
If this option is not specified, an absolute file is produced. When
|
|
linking C++ programs, this option \c
|
|
.I will not\c
|
|
\& resolve references to
|
|
constructors; \c
|
|
.B \-Ur\c
|
|
\& is an alternative.
|
|
|
|
This option does the same as \c
|
|
.B \-i\c
|
|
\&.
|
|
|
|
.TP
|
|
.B \-rpath\ \fIdirectory
|
|
Add a directory to the runtime library search path. This is used when
|
|
linking an ELF executable with shared objects. All
|
|
.B \-rpath
|
|
arguments are concatenated and passed to the runtime linker, which uses
|
|
them to locate shared objects at runtime. The
|
|
.B \-rpath
|
|
option is also used when locating shared objects which are needed by
|
|
shared objects explicitly included in the link; see the description of
|
|
the
|
|
.B \-rpath\-link
|
|
option. If
|
|
.B \-rpath
|
|
is not used when linking an ELF executable, the contents of the
|
|
environment variable
|
|
.B LD_RUN_PATH
|
|
will be used if it is defined.
|
|
|
|
The
|
|
.B \-rpath
|
|
option may also be used on SunOS. By default, on SunOS, the linker
|
|
will form a runtime search path out of all the
|
|
.B \-L
|
|
options it is given. If a
|
|
.B \-rpath
|
|
option is used, the runtime search path will be formed exclusively
|
|
using the
|
|
.B \-rpath
|
|
options, ignoring
|
|
the
|
|
.B \-L
|
|
options. This can be useful when using gcc, which adds many
|
|
.B \-L
|
|
options which may be on NFS mounted filesystems.
|
|
|
|
.TP
|
|
.B \-rpath\-link\ \fIdirectory
|
|
When using ELF or SunOS, one shared library may require another. This
|
|
happens when an
|
|
.B ld\ \-shared
|
|
link includes a shared library as one of the input files.
|
|
|
|
When the linker encounters such a dependency when doing a non-shared,
|
|
non-relocateable 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
|
|
.B \-rpath\-link
|
|
option specifies the first set of directories to search. The
|
|
.B \-rpath\-link
|
|
option may specify a sequence of directory names either by specifying
|
|
a list of names separated by colons, or by appearing multiple times.
|
|
|
|
If the required shared library is not found, the linker will issue a
|
|
warning and continue with the link.
|
|
|
|
.TP
|
|
.B \-S
|
|
Omits debugger symbol information (but not all symbols) from the output file.
|
|
|
|
.TP
|
|
.B \-s
|
|
Omits all symbol information from the output file.
|
|
|
|
.TP
|
|
.B \-shared
|
|
Create a shared library. This is currently only supported on ELF and
|
|
SunOS platforms (on SunOS it is not required, as the linker will
|
|
automatically create a shared library when there are undefined symbols
|
|
and the
|
|
.B \-e
|
|
option is not used).
|
|
|
|
.TP
|
|
.B \-sort\-common
|
|
Normally, when
|
|
.B ld
|
|
places the global common symbols in the appropriate output sections,
|
|
it sorts them by size. 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. This option disables that sorting.
|
|
|
|
.TP
|
|
.B \-split\-by\-reloc\ \fIcount
|
|
Trys to creates extra sections in the output file so that no single
|
|
output section in the file contains more than
|
|
.I count
|
|
relocations.
|
|
This is useful when generating huge relocatable for downloading into
|
|
certain real time kernels with the COFF object file format; since COFF
|
|
cannot represent more than 65535 relocations in a single section.
|
|
Note that this will fail to work with object file formats which do not
|
|
support arbitrary sections. The linker will not split up individual
|
|
input sections for redistribution, so if a single input section
|
|
contains more than
|
|
.I count
|
|
relocations one output section will contain that many relocations.
|
|
|
|
.TP
|
|
.B \-split\-by\-file
|
|
Similar to
|
|
.B \-split\-by\-reloc
|
|
but creates a new output section for each input file.
|
|
|
|
.TP
|
|
.BI "--section-start " "sectionname" "\fR=\fP"org
|
|
Locate a section in the output file at the absolute
|
|
address given by \c
|
|
.I org\c
|
|
\&. \c
|
|
\c
|
|
.I org\c
|
|
\& must be a hexadecimal integer.
|
|
You may use this option as many
|
|
times as necessary to locate multiple sections in the command
|
|
line. If you need more elaborate expressions, consider
|
|
using the linker command language from a script.
|
|
|
|
.TP
|
|
.BI "\-Tbss " "org"\c
|
|
.TP
|
|
.BI "\-Tdata " "org"\c
|
|
.TP
|
|
.BI "\-Ttext " "org"\c
|
|
Use \c
|
|
.I org\c
|
|
\& as the starting address for\(em\&respectively\(em\&the
|
|
\c
|
|
.B bss\c
|
|
\&, \c
|
|
.B data\c
|
|
\&, or the \c
|
|
.B text\c
|
|
\& segment of the output file.
|
|
\c
|
|
.I org\c
|
|
\& must be a hexadecimal integer.
|
|
|
|
.TP
|
|
.BI "\-T " "commandfile"
|
|
Equivalent to \c
|
|
.B \-c \c
|
|
.I commandfile\c
|
|
\&\c
|
|
\&; supported for compatibility with
|
|
other tools.
|
|
|
|
.TP
|
|
.B \-t
|
|
Prints names of input files as \c
|
|
.B ld\c
|
|
\& processes them.
|
|
|
|
.TP
|
|
.BI "\-u " "sym"
|
|
Forces \c
|
|
.I sym\c
|
|
\& to be entered in the output file as an undefined symbol.
|
|
This may, for example, trigger linking of additional modules from
|
|
standard libraries. \c
|
|
.B \-u\c
|
|
\& may be repeated with different option
|
|
arguments to enter additional undefined symbols.
|
|
|
|
.TP
|
|
.B \-Ur
|
|
For anything other than C++ programs, this option is equivalent to
|
|
\c
|
|
.B \-r\c
|
|
\&: it generates relocatable output\(em\&i.e., an output file that can in
|
|
turn serve as input to \c
|
|
.B ld\c
|
|
\&. When linking C++ programs, \c
|
|
.B \-Ur
|
|
.I will\c
|
|
\& resolve references to constructors, unlike \c
|
|
.B \-r\c
|
|
\&.
|
|
|
|
.TP
|
|
.B \-\-verbose
|
|
Display the version number for \c
|
|
.B ld
|
|
and list the supported emulations.
|
|
Display which input files can and can not be opened.
|
|
|
|
.TP
|
|
.B \-v, \-V
|
|
Display the version number for \c
|
|
.B ld\c
|
|
\&.
|
|
The
|
|
.B \-V
|
|
option also lists the supported emulations.
|
|
|
|
.TP
|
|
.B \-\-version
|
|
Display the version number for \c
|
|
.B ld
|
|
and exit.
|
|
|
|
.TP
|
|
.B \-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.
|
|
|
|
.TP
|
|
.B \-warn\-constructors
|
|
Warn if any global constructors are used. This is only useful for a
|
|
few object file formats. For formats like COFF or ELF, the linker can
|
|
not detect the use of global constructors.
|
|
|
|
.TP
|
|
.B \-warn\-multiple\-gp
|
|
Warn if the output file requires multiple global-pointer values. This
|
|
option is only meaningful for certain processors, such as the Alpha.
|
|
|
|
.TP
|
|
.B \-warn\-once
|
|
Only warn once for each undefined symbol, rather than once per module
|
|
which refers to it.
|
|
|
|
.TP
|
|
.B \-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 SECTIONS command does not specify a start address for the
|
|
section.
|
|
|
|
.TP
|
|
.B \-\-whole\-archive
|
|
For each archive mentioned on the command line after the
|
|
.B \-\-whole\-archive
|
|
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.
|
|
|
|
.TP
|
|
.B \-\-no\-whole\-archive
|
|
Turn off the effect of the
|
|
.B \-\-whole\-archive
|
|
option for archives which appear later on the command line.
|
|
|
|
.TP
|
|
.BI "--wrap " "symbol"
|
|
Use a wrapper function for
|
|
.I symbol.
|
|
Any undefined reference to
|
|
.I symbol
|
|
will be resolved to
|
|
.BI "__wrap_" "symbol".
|
|
Any undefined reference to
|
|
.BI "__real_" "symbol"
|
|
will be resolved to
|
|
.I symbol.
|
|
|
|
.TP
|
|
.B \-X
|
|
Delete all temporary local symbols. For most targets, this is all local
|
|
symbols whose names begin with `\|\c
|
|
.B L\c
|
|
\|'.
|
|
|
|
.TP
|
|
.B \-x
|
|
Delete all local symbols.
|
|
|
|
.PP
|
|
|
|
.SH ENVIRONMENT
|
|
\c
|
|
You can change the behavior of
|
|
.B ld\c
|
|
\& with the environment variable \c
|
|
.B GNUTARGET\c
|
|
\&.
|
|
|
|
\c
|
|
.B GNUTARGET\c
|
|
\& determines the input-file object format if you don't
|
|
use \c
|
|
.B \-b\c
|
|
\& (or its synonym \c
|
|
.B \-format\c
|
|
\&). Its value should be one
|
|
of the BFD names for an input format. If there is no
|
|
\c
|
|
.B GNUTARGET\c
|
|
\& in the environment, \c
|
|
.B ld\c
|
|
\& uses the natural format
|
|
of the host. If \c
|
|
.B GNUTARGET\c
|
|
\& is set to \c
|
|
.B default\c
|
|
\& then BFD attempts to discover the
|
|
input format by examining binary input files; this method often
|
|
succeeds, but there are potential ambiguities, since there is no method
|
|
of ensuring that the magic number used to flag object-file formats is
|
|
unique. However, the configuration procedure for BFD on each system
|
|
places the conventional format for that system first in the search-list,
|
|
so ambiguities are resolved in favor of convention.
|
|
|
|
.PP
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR objdump ( 1 )
|
|
.br
|
|
.br
|
|
.RB "`\|" ld "\|' and `\|" binutils "\|'"
|
|
entries in
|
|
.B info\c
|
|
.br
|
|
.I
|
|
ld: the GNU linker\c
|
|
, Steve Chamberlain and Roland Pesch;
|
|
.I
|
|
The GNU Binary Utilities\c
|
|
, Roland H. Pesch.
|
|
|
|
.SH COPYING
|
|
Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 1998, 2000 Free Software Foundation, Inc.
|
|
.PP
|
|
This document is distributed under the terms of the GNU Free
|
|
Documentation License, version 1.1. That license is described in the
|
|
sources for this manual page, but it is not displayed here in order to
|
|
make this manual more consise. Copies of this license can also be
|
|
obtained from: http://www.gnu.org/copyleft/.
|
|
|
|
\" .SH GNU Free Documentation License
|
|
\" Version 1.1, March 2000
|
|
|
|
\" Copyright (C) 2000 Free Software Foundation, Inc.
|
|
\" 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
|
|
\" Everyone is permitted to copy and distribute verbatim
|
|
\" copies of this license document, but changing it is
|
|
\" not allowed.
|
|
\" .PP
|
|
\" 0. PREAMBLE
|
|
\" .PP
|
|
\" The purpose of this License is to make a manual, textbook, or other
|
|
\" written document "free" in the sense of freedom: to assure everyone
|
|
\" the effective freedom to copy and redistribute it, with or without
|
|
\" modifying it, either commercially or noncommercially. Secondarily,
|
|
\" this License preserves for the author and publisher a way to get
|
|
\" credit for their work, while not being considered responsible for
|
|
\" modifications made by others.
|
|
\" .PP
|
|
\" This License is a kind of "copyleft", which means that derivative
|
|
\" works of the document must themselves be free in the same sense. It
|
|
\" complements the GNU General Public License, which is a copyleft
|
|
\" license designed for free software.
|
|
\" .PP
|
|
\" We have designed this License in order to use it for manuals for free
|
|
\" software, because free software needs free documentation: a free
|
|
\" program should come with manuals providing the same freedoms that the
|
|
\" software does. But this License is not limited to software manuals;
|
|
\" it can be used for any textual work, regardless of subject matter or
|
|
\" whether it is published as a printed book. We recommend this License
|
|
\" principally for works whose purpose is instruction or reference.
|
|
\" .PP
|
|
\" 1. APPLICABILITY AND DEFINITIONS
|
|
\" .PP
|
|
\" This License applies to any manual or other work that contains a
|
|
\" notice placed by the copyright holder saying it can be distributed
|
|
\" under the terms of this License. The "Document", below, refers to any
|
|
\" such manual or work. Any member of the public is a licensee, and is
|
|
\" addressed as "you".
|
|
\" .PP
|
|
\" A "Modified Version" of the Document means any work containing the
|
|
\" Document or a portion of it, either copied verbatim, or with
|
|
\" modifications and/or translated into another language.
|
|
\" .PP
|
|
\" A "Secondary Section" is a named appendix or a front-matter section of
|
|
\" the Document that deals exclusively with the relationship of the
|
|
\" publishers or authors of the Document to the Document's overall subject
|
|
\" (or to related matters) and contains nothing that could fall directly
|
|
\" within that overall subject. (For example, if the Document is in part a
|
|
\" textbook of mathematics, a Secondary Section may not explain any
|
|
\" mathematics.) The relationship could be a matter of historical
|
|
\" connection with the subject or with related matters, or of legal,
|
|
\" commercial, philosophical, ethical or political position regarding
|
|
\" them.
|
|
\" .PP
|
|
\" The "Invariant Sections" are certain Secondary Sections whose titles
|
|
\" are designated, as being those of Invariant Sections, in the notice
|
|
\" that says that the Document is released under this License.
|
|
\" .PP
|
|
\" The "Cover Texts" are certain short passages of text that are listed,
|
|
\" as Front-Cover Texts or Back-Cover Texts, in the notice that says that
|
|
\" the Document is released under this License.
|
|
\" .PP
|
|
\" A "Transparent" copy of the Document means a machine-readable copy,
|
|
\" represented in a format whose specification is available to the
|
|
\" general public, whose contents can be viewed and edited directly and
|
|
\" straightforwardly with generic text editors or (for images composed of
|
|
\" pixels) generic paint programs or (for drawings) some widely available
|
|
\" drawing editor, and that is suitable for input to text formatters or
|
|
\" for automatic translation to a variety of formats suitable for input
|
|
\" to text formatters. A copy made in an otherwise Transparent file
|
|
\" format whose markup has been designed to thwart or discourage
|
|
\" subsequent modification by readers is not Transparent. A copy that is
|
|
\" not "Transparent" is called "Opaque".
|
|
\" .PP
|
|
\" Examples of suitable formats for Transparent copies include plain
|
|
\" ASCII without markup, Texinfo input format, LaTeX input format, SGML
|
|
\" or XML using a publicly available DTD, and standard-conforming simple
|
|
\" HTML designed for human modification. Opaque formats include
|
|
\" PostScript, PDF, proprietary formats that can be read and edited only
|
|
\" by proprietary word processors, SGML or XML for which the DTD and/or
|
|
\" processing tools are not generally available, and the
|
|
\" machine-generated HTML produced by some word processors for output
|
|
\" purposes only.
|
|
\" .PP
|
|
\" The "Title Page" means, for a printed book, the title page itself,
|
|
\" plus such following pages as are needed to hold, legibly, the material
|
|
\" this License requires to appear in the title page. For works in
|
|
\" formats which do not have any title page as such, "Title Page" means
|
|
\" the text near the most prominent appearance of the work's title,
|
|
\" preceding the beginning of the body of the text.
|
|
\" .PP
|
|
\" 2. VERBATIM COPYING
|
|
\" .PP
|
|
\" You may copy and distribute the Document in any medium, either
|
|
\" commercially or noncommercially, provided that this License, the
|
|
\" copyright notices, and the license notice saying this License applies
|
|
\" to the Document are reproduced in all copies, and that you add no other
|
|
\" conditions whatsoever to those of this License. You may not use
|
|
\" technical measures to obstruct or control the reading or further
|
|
\" copying of the copies you make or distribute. However, you may accept
|
|
\" compensation in exchange for copies. If you distribute a large enough
|
|
\" number of copies you must also follow the conditions in section 3.
|
|
\" .PP
|
|
\" You may also lend copies, under the same conditions stated above, and
|
|
\" you may publicly display copies.
|
|
\" .PP
|
|
\" 3. COPYING IN QUANTITY
|
|
\" .PP
|
|
\" If you publish printed copies of the Document numbering more than 100,
|
|
\" and the Document's license notice requires Cover Texts, you must enclose
|
|
\" the copies in covers that carry, clearly and legibly, all these Cover
|
|
\" Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
|
|
\" the back cover. Both covers must also clearly and legibly identify
|
|
\" you as the publisher of these copies. The front cover must present
|
|
\" the full title with all words of the title equally prominent and
|
|
\" visible. You may add other material on the covers in addition.
|
|
\" Copying with changes limited to the covers, as long as they preserve
|
|
\" the title of the Document and satisfy these conditions, can be treated
|
|
\" as verbatim copying in other respects.
|
|
\" .PP
|
|
\" If the required texts for either cover are too voluminous to fit
|
|
\" legibly, you should put the first ones listed (as many as fit
|
|
\" reasonably) on the actual cover, and continue the rest onto adjacent
|
|
\" pages.
|
|
\" .PP
|
|
\" If you publish or distribute Opaque copies of the Document numbering
|
|
\" more than 100, you must either include a machine-readable Transparent
|
|
\" copy along with each Opaque copy, or state in or with each Opaque copy
|
|
\" a publicly-accessible computer-network location containing a complete
|
|
\" Transparent copy of the Document, free of added material, which the
|
|
\" general network-using public has access to download anonymously at no
|
|
\" charge using public-standard network protocols. If you use the latter
|
|
\" option, you must take reasonably prudent steps, when you begin
|
|
\" distribution of Opaque copies in quantity, to ensure that this
|
|
\" Transparent copy will remain thus accessible at the stated location
|
|
\" until at least one year after the last time you distribute an Opaque
|
|
\" copy (directly or through your agents or retailers) of that edition to
|
|
\" the public.
|
|
\" .PP
|
|
\" It is requested, but not required, that you contact the authors of the
|
|
\" Document well before redistributing any large number of copies, to give
|
|
\" them a chance to provide you with an updated version of the Document.
|
|
\" .PP
|
|
\" 4. MODIFICATIONS
|
|
\" .PP
|
|
\" You may copy and distribute a Modified Version of the Document under
|
|
\" the conditions of sections 2 and 3 above, provided that you release
|
|
\" the Modified Version under precisely this License, with the Modified
|
|
\" Version filling the role of the Document, thus licensing distribution
|
|
\" and modification of the Modified Version to whoever possesses a copy
|
|
\" of it. In addition, you must do these things in the Modified Version:
|
|
\" .PP
|
|
\" A. Use in the Title Page (and on the covers, if any) a title distinct
|
|
\" from that of the Document, and from those of previous versions
|
|
\" (which should, if there were any, be listed in the History section
|
|
\" of the Document). You may use the same title as a previous version
|
|
\" if the original publisher of that version gives permission.
|
|
\" .PP
|
|
\" B. List on the Title Page, as authors, one or more persons or entities
|
|
\" responsible for authorship of the modifications in the Modified
|
|
\" Version, together with at least five of the principal authors of the
|
|
\" Document (all of its principal authors, if it has less than five).
|
|
\" .PP
|
|
\" C. State on the Title page the name of the publisher of the
|
|
\" Modified Version, as the publisher.
|
|
\" .PP
|
|
\" D. Preserve all the copyright notices of the Document.
|
|
\" .PP
|
|
\" E. Add an appropriate copyright notice for your modifications
|
|
\" adjacent to the other copyright notices.
|
|
\" .PP
|
|
\" F. Include, immediately after the copyright notices, a license notice
|
|
\" giving the public permission to use the Modified Version under the
|
|
\" terms of this License, in the form shown in the Addendum below.
|
|
\" Preserve in that license notice the full lists of Invariant Sections
|
|
\" and required Cover Texts given in the Document's license notice.
|
|
\" .PP
|
|
\" H. Include an unaltered copy of this License.
|
|
\" .PP
|
|
\" I. Preserve the section entitled "History", and its title, and add to
|
|
\" it an item stating at least the title, year, new authors, and
|
|
\" publisher of the Modified Version as given on the Title Page. If
|
|
\" there is no section entitled "History" in the Document, create one
|
|
\" stating the title, year, authors, and publisher of the Document as
|
|
\" given on its Title Page, then add an item describing the Modified
|
|
\" Version as stated in the previous sentence.
|
|
\" .PP
|
|
\" J. Preserve the network location, if any, given in the Document for
|
|
\" public access to a Transparent copy of the Document, and likewise
|
|
\" the network locations given in the Document for previous versions
|
|
\" it was based on. These may be placed in the "History" section.
|
|
\" You may omit a network location for a work that was published at
|
|
\" least four years before the Document itself, or if the original
|
|
\" publisher of the version it refers to gives permission.
|
|
\" .PP
|
|
\" K. In any section entitled "Acknowledgements" or "Dedications",
|
|
\" preserve the section's title, and preserve in the section all the
|
|
\" substance and tone of each of the contributor acknowledgements
|
|
\" and/or dedications given therein.
|
|
\" .PP
|
|
\" L. Preserve all the Invariant Sections of the Document,
|
|
\" unaltered in their text and in their titles. Section numbers
|
|
\" or the equivalent are not considered part of the section titles.
|
|
\" .PP
|
|
\" M. Delete any section entitled "Endorsements". Such a section
|
|
\" may not be included in the Modified Version.
|
|
\" .PP
|
|
\" N. Do not retitle any existing section as "Endorsements"
|
|
\" or to conflict in title with any Invariant Section.
|
|
\" .PP
|
|
\" If the Modified Version includes new front-matter sections or
|
|
\" appendices that qualify as Secondary Sections and contain no material
|
|
\" copied from the Document, you may at your option designate some or all
|
|
\" of these sections as invariant. To do this, add their titles to the
|
|
\" list of Invariant Sections in the Modified Version's license notice.
|
|
\" These titles must be distinct from any other section titles.
|
|
\" .PP
|
|
\" You may add a section entitled "Endorsements", provided it contains
|
|
\" nothing but endorsements of your Modified Version by various
|
|
\" parties--for example, statements of peer review or that the text has
|
|
\" been approved by an organization as the authoritative definition of a
|
|
\" standard.
|
|
\" .PP
|
|
\" You may add a passage of up to five words as a Front-Cover Text, and a
|
|
\" passage of up to 25 words as a Back-Cover Text, to the end of the list
|
|
\" of Cover Texts in the Modified Version. Only one passage of
|
|
\" Front-Cover Text and one of Back-Cover Text may be added by (or
|
|
\" through arrangements made by) any one entity. If the Document already
|
|
\" includes a cover text for the same cover, previously added by you or
|
|
\" by arrangement made by the same entity you are acting on behalf of,
|
|
\" you may not add another; but you may replace the old one, on explicit
|
|
\" permission from the previous publisher that added the old one.
|
|
\" .PP
|
|
\" The author(s) and publisher(s) of the Document do not by this License
|
|
\" give permission to use their names for publicity for or to assert or
|
|
\" imply endorsement of any Modified Version.
|
|
\" .PP
|
|
|
|
\" 5. COMBINING DOCUMENTS
|
|
\" .PP
|
|
\" You may combine the Document with other documents released under this
|
|
\" License, under the terms defined in section 4 above for modified
|
|
\" versions, provided that you include in the combination all of the
|
|
\" Invariant Sections of all of the original documents, unmodified, and
|
|
\" list them all as Invariant Sections of your combined work in its
|
|
\" license notice.
|
|
\" .PP
|
|
\" The combined work need only contain one copy of this License, and
|
|
\" multiple identical Invariant Sections may be replaced with a single
|
|
\" copy. If there are multiple Invariant Sections with the same name but
|
|
\" different contents, make the title of each such section unique by
|
|
\" adding at the end of it, in parentheses, the name of the original
|
|
\" author or publisher of that section if known, or else a unique number.
|
|
\" Make the same adjustment to the section titles in the list of
|
|
\" Invariant Sections in the license notice of the combined work.
|
|
\" .PP
|
|
\" In the combination, you must combine any sections entitled "History"
|
|
\" in the various original documents, forming one section entitled
|
|
\" "History"; likewise combine any sections entitled "Acknowledgements",
|
|
\" and any sections entitled "Dedications". You must delete all sections
|
|
\" entitled "Endorsements."
|
|
\" .PP
|
|
|
|
\" 6. COLLECTIONS OF DOCUMENTS
|
|
\" .PP
|
|
\" You may make a collection consisting of the Document and other documents
|
|
\" released under this License, and replace the individual copies of this
|
|
\" License in the various documents with a single copy that is included in
|
|
\" the collection, provided that you follow the rules of this License for
|
|
\" verbatim copying of each of the documents in all other respects.
|
|
\" .PP
|
|
\" You may extract a single document from such a collection, and distribute
|
|
\" it individually under this License, provided you insert a copy of this
|
|
\" License into the extracted document, and follow this License in all
|
|
\" other respects regarding verbatim copying of that document.
|
|
\" .PP
|
|
|
|
\" 7. AGGREGATION WITH INDEPENDENT WORKS
|
|
\" .PP
|
|
\" A compilation of the Document or its derivatives with other separate
|
|
\" and independent documents or works, in or on a volume of a storage or
|
|
\" distribution medium, does not as a whole count as a Modified Version
|
|
\" of the Document, provided no compilation copyright is claimed for the
|
|
\" compilation. Such a compilation is called an "aggregate", and this
|
|
\" License does not apply to the other self-contained works thus compiled
|
|
\" with the Document, on account of their being thus compiled, if they
|
|
\" are not themselves derivative works of the Document.
|
|
\" .PP
|
|
\" If the Cover Text requirement of section 3 is applicable to these
|
|
\" copies of the Document, then if the Document is less than one quarter
|
|
\" of the entire aggregate, the Document's Cover Texts may be placed on
|
|
\" covers that surround only the Document within the aggregate.
|
|
\" Otherwise they must appear on covers around the whole aggregate.
|
|
\" .PP
|
|
|
|
\" 8. TRANSLATION
|
|
\" .PP
|
|
\" Translation is considered a kind of modification, so you may
|
|
\" distribute translations of the Document under the terms of section 4.
|
|
\" Replacing Invariant Sections with translations requires special
|
|
\" permission from their copyright holders, but you may include
|
|
\" translations of some or all Invariant Sections in addition to the
|
|
\" original versions of these Invariant Sections. You may include a
|
|
\" translation of this License provided that you also include the
|
|
\" original English version of this License. In case of a disagreement
|
|
\" between the translation and the original English version of this
|
|
\" License, the original English version will prevail.
|
|
\" .PP
|
|
|
|
\" 9. TERMINATION
|
|
\" .PP
|
|
\" You may not copy, modify, sublicense, or distribute the Document except
|
|
\" as expressly provided for under this License. Any other attempt to
|
|
\" copy, modify, sublicense or distribute the Document is void, and will
|
|
\" automatically terminate your rights under this License. However,
|
|
\" parties who have received copies, or rights, from you under this
|
|
\" License will not have their licenses terminated so long as such
|
|
\" parties remain in full compliance.
|
|
\" .PP
|
|
|
|
\" 10. FUTURE REVISIONS OF THIS LICENSE
|
|
\" .PP
|
|
\" The Free Software Foundation may publish new, revised versions
|
|
\" of the GNU Free Documentation License from time to time. Such new
|
|
\" versions will be similar in spirit to the present version, but may
|
|
\" differ in detail to address new problems or concerns. See
|
|
\" http://www.gnu.org/copyleft/.
|
|
\" .PP
|
|
\" Each version of the License is given a distinguishing version number.
|
|
\" If the Document specifies that a particular numbered version of this
|
|
\" License "or any later version" applies to it, you have the option of
|
|
\" following the terms and conditions either of that specified version or
|
|
\" of any later version that has been published (not as a draft) by the
|
|
\" Free Software Foundation. If the Document does not specify a version
|
|
\" number of this License, you may choose any version ever published (not
|
|
\" as a draft) by the Free Software Foundation.
|
|
\" .PP
|
|
|
|
\" ADDENDUM: How to use this License for your documents
|
|
\" .PP
|
|
\" To use this License in a document you have written, include a copy of
|
|
\" the License in the document and put the following copyright and
|
|
\" license notices just after the title page:
|
|
\" .PP
|
|
\" Copyright (c) YEAR YOUR NAME.
|
|
\" Permission is granted to copy, distribute and/or
|
|
\" modify this document under the terms of the GNU
|
|
\" Free Documentation License, Version 1.1 or any later
|
|
\" version published by the Free Software Foundation;
|
|
\" with the Invariant Sections being LIST THEIR TITLES,
|
|
\" with the Front-Cover Texts being LIST, and with the
|
|
\" Back-Cover Texts being LIST. A copy of the license
|
|
\" is included in the section entitled "GNU Free
|
|
\" Documentation License".
|
|
\" .PP
|
|
\" If you have no Invariant Sections, write "with no Invariant Sections"
|
|
\" instead of saying which ones are invariant. If you have no
|
|
\" Front-Cover Texts, write "no Front-Cover Texts" instead of
|
|
\" "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
|
|
\" .PP
|
|
\" If your document contains nontrivial examples of program code, we
|
|
\" recommend releasing these examples in parallel under your choice of
|
|
\" free software license, such as the GNU General Public License,
|
|
\" to permit their use in free software.
|