aboutsummaryrefslogtreecommitdiff
path: root/ld
diff options
context:
space:
mode:
authorSandra Loosemore <sandra@codesourcery.com>2009-02-24 18:06:27 +0000
committerSandra Loosemore <sandra@codesourcery.com>2009-02-24 18:06:27 +0000
commit2509a395cb1b6f6dd5b72f84d80693eaff977d31 (patch)
tree531f2aeb69ba2f8edd9c6a4eb44f4a7f54514169 /ld
parent02529b48440347f8398a73ecbdae07a491ec370c (diff)
downloadgdb-2509a395cb1b6f6dd5b72f84d80693eaff977d31.zip
gdb-2509a395cb1b6f6dd5b72f84d80693eaff977d31.tar.gz
gdb-2509a395cb1b6f6dd5b72f84d80693eaff977d31.tar.bz2
2009-02-24 Sandra Loosemore <sandra@codesourcery.com>
ld/ * ld.texinfo (Options): Correct typos in example. Recommend using joined forms of syntax for passing options with arguments from a driver. (-a): Use consistent syntax for documenting option arguments. Clean up indexing and markup. (-A/--architecture): Likewise. (-f/--auxiliary): Likewise. (-F/--filter): Likewise. (-fini): Likewise. (-G/--gpsize): Likewise. (-h/-soname):Likewise. (-init): Likewise. (-l/--library): Likewise. (-L/--library-path): Likewise. (-m): Likewise. (--defsym): Likewise. (-I/--dynamic-linker): Likewise. (-Map): Likewise. (--oformat): Likewise. (--retain-symbols-file): Likewise. (-rpath): Likewise. (-rpath-link): Likewise. (--sort-common): Likewise. (--sort-section): Likewise. (--split-by-file): Likewise. (--split-by-reloc): Likewise. (--sysroot): Likewise. (--section-start): Likewise. (-Tbss, -Tdata, -Ttext): Likewise. (-Ttext-segment): Likewise. (--version-script): Likewise. (--wrap): Likewise.
Diffstat (limited to 'ld')
-rw-r--r--ld/ChangeLog35
-rw-r--r--ld/ld.texinfo137
2 files changed, 110 insertions, 62 deletions
diff --git a/ld/ChangeLog b/ld/ChangeLog
index e616d5b..f61f2ce 100644
--- a/ld/ChangeLog
+++ b/ld/ChangeLog
@@ -1,3 +1,38 @@
+2009-02-24 Sandra Loosemore <sandra@codesourcery.com>
+
+ * ld.texinfo (Options): Correct typos in example. Recommend
+ using joined forms of syntax for passing options with arguments
+ from a driver.
+ (-a): Use consistent syntax for documenting option arguments.
+ Clean up indexing and markup.
+ (-A/--architecture): Likewise.
+ (-f/--auxiliary): Likewise.
+ (-F/--filter): Likewise.
+ (-fini): Likewise.
+ (-G/--gpsize): Likewise.
+ (-h/-soname):Likewise.
+ (-init): Likewise.
+ (-l/--library): Likewise.
+ (-L/--library-path): Likewise.
+ (-m): Likewise.
+ (--defsym): Likewise.
+ (-I/--dynamic-linker): Likewise.
+ (-Map): Likewise.
+ (--oformat): Likewise.
+ (--retain-symbols-file): Likewise.
+ (-rpath): Likewise.
+ (-rpath-link): Likewise.
+ (--sort-common): Likewise.
+ (--sort-section): Likewise.
+ (--split-by-file): Likewise.
+ (--split-by-reloc): Likewise.
+ (--sysroot): Likewise.
+ (--section-start): Likewise.
+ (-Tbss, -Tdata, -Ttext): Likewise.
+ (-Ttext-segment): Likewise.
+ (--version-script): Likewise.
+ (--wrap): Likewise.
+
2009-02-18 Dave Korn <dave.korn.cygwin@gmail.com>
* ld.texinfo: Update to mention long section name options.
diff --git a/ld/ld.texinfo b/ld/ld.texinfo
index 082f655..e35775d 100644
--- a/ld/ld.texinfo
+++ b/ld/ld.texinfo
@@ -335,11 +335,20 @@ prefixed by @samp{-Wl,} (or whatever is appropriate for the particular
compiler driver) like this:
@smallexample
- gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
+ gcc -Wl,--start-group foo.o bar.o -Wl,--end-group
@end smallexample
This is important, because otherwise the compiler driver program may
-silently drop the linker options, resulting in a bad link.
+silently drop the linker options, resulting in a bad link. Confusion
+may also arise when passing options that require values through a
+driver, as the use of a space between option and argument acts as
+a separator, and causes the driver to pass only the option to the linker
+and the argument to the compiler. In this case, it is simplest to use
+the joined forms of both single- and multiple-letter options, such as:
+
+@smallexample
+ gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map
+@end smallexample
Here is a table of the generic command line switches accepted by the GNU
linker:
@@ -347,8 +356,8 @@ linker:
@table @gcctabopt
@include at-file.texi
-@kindex -a@var{keyword}
-@item -a@var{keyword}
+@kindex -a @var{keyword}
+@item -a @var{keyword}
This option is supported for HP/UX compatibility. The @var{keyword}
argument must be one of the strings @samp{archive}, @samp{shared}, or
@samp{default}. @samp{-aarchive} is functionally equivalent to
@@ -357,8 +366,8 @@ to @samp{-Bdynamic}. This option may be used any number of times.
@ifset I960
@cindex architectures
-@kindex -A@var{arch}
-@item -A@var{architecture}
+@kindex -A @var{arch}
+@item -A @var{architecture}
@kindex --architecture=@var{arch}
@itemx --architecture=@var{architecture}
In the current release of @command{ld}, this option is useful only for the
@@ -514,10 +523,10 @@ Link big-endian objects. This affects the default output format.
Link little-endian objects. This affects the default output format.
@end ifclear
-@kindex -f
-@kindex --auxiliary
-@item -f
-@itemx --auxiliary @var{name}
+@kindex -f @var{name}
+@kindex --auxiliary=@var{name}
+@item -f @var{name}
+@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
@@ -536,10 +545,10 @@ machine specific performance.
This option may be specified more than once. The DT_AUXILIARY entries
will be created in the order in which they appear on the command line.
-@kindex -F
-@kindex --filter
+@kindex -F @var{name}
+@kindex --filter=@var{name}
@item -F @var{name}
-@itemx --filter @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
@@ -566,8 +575,8 @@ The @sc{gnu} linker will ignore the @option{-F} option when not
creating an ELF shared object.
@cindex finalization function
-@kindex -fini
-@item -fini @var{name}
+@kindex -fini=@var{name}
+@item -fini=@var{name}
When creating an ELF executable or shared object, call NAME when the
executable or shared object is unloaded, by setting DT_FINI to the
address of the function. By default, the linker uses @code{_fini} as
@@ -577,10 +586,10 @@ the function to call.
@item -g
Ignored. Provided for compatibility with other tools.
-@kindex -G
-@kindex --gpsize
+@kindex -G @var{value}
+@kindex --gpsize=@var{value}
@cindex object size
-@item -G@var{value}
+@item -G @var{value}
@itemx --gpsize=@var{value}
Set the maximum size of objects to be optimized using the GP register to
@var{size}. This is only meaningful for object file formats such as
@@ -588,9 +597,9 @@ MIPS ECOFF which supports putting large and small objects into different
sections. This is ignored for other object file formats.
@cindex runtime library name
-@kindex -h@var{name}
+@kindex -h @var{name}
@kindex -soname=@var{name}
-@item -h@var{name}
+@item -h @var{name}
@itemx -soname=@var{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
@@ -604,17 +613,17 @@ field rather than the using the file name given to the linker.
Perform an incremental link (same as option @samp{-r}).
@cindex initialization function
-@kindex -init
-@item -init @var{name}
+@kindex -init=@var{name}
+@item -init=@var{name}
When creating an ELF executable or shared object, call NAME when the
executable or shared object is loaded, by setting DT_INIT to the address
of the function. By default, the linker uses @code{_init} as the
function to call.
@cindex archive files, from cmd line
-@kindex -l@var{namespec}
+@kindex -l @var{namespec}
@kindex --library=@var{namespec}
-@item -l@var{namespec}
+@item -l @var{namespec}
@itemx --library=@var{namespec}
Add the archive or object file specified by @var{namespec} to the
list of files to link. This option may be used any number of times.
@@ -650,9 +659,9 @@ behaviour of the AIX linker.
@end ifset
@cindex search directory, from cmd line
-@kindex -L@var{dir}
+@kindex -L @var{dir}
@kindex --library-path=@var{dir}
-@item -L@var{searchdir}
+@item -L @var{searchdir}
@itemx --library-path=@var{searchdir}
Add path @var{searchdir} to the list of paths that @command{ld} will search
for archive libraries and @command{ld} control scripts. You may use this
@@ -677,7 +686,7 @@ at the point in which the linker script appears in the command line.
@cindex emulation
@kindex -m @var{emulation}
-@item -m@var{emulation}
+@item -m @var{emulation}
Emulate the @var{emulation} linker. You can list the available
emulations with the @samp{--verbose} or @samp{-V} options.
@@ -1244,8 +1253,8 @@ duplicate when there are many dynamic modules with specialized search
paths for runtime symbol resolution.
@cindex symbols, from command line
-@kindex --defsym @var{symbol}=@var{exp}
-@item --defsym @var{symbol}=@var{expression}
+@kindex --defsym=@var{symbol}=@var{exp}
+@item --defsym=@var{symbol}=@var{expression}
Create a global symbol in the output file, containing the absolute
address given by @var{expression}. You may use this option as many
times as necessary to define multiple symbols in the command line. A
@@ -1275,8 +1284,9 @@ is set. These options may be used to override the default.
@cindex dynamic linker, from command line
@kindex -I@var{file}
-@kindex --dynamic-linker @var{file}
-@item --dynamic-linker @var{file}
+@kindex --dynamic-linker=@var{file}
+@item -I@var{file}
+@itemx --dynamic-linker=@var{file}
Set the name of the dynamic linker. This is only meaningful when
generating dynamically linked ELF executables. The default dynamic
linker is normally correct; don't use this unless you know what you are
@@ -1347,8 +1357,8 @@ Print a summary of the command-line options on the standard output and exit.
@item --target-help
Print a summary of all target specific options on the standard output and exit.
-@kindex -Map
-@item -Map @var{mapfile}
+@kindex -Map=@var{mapfile}
+@item -Map=@var{mapfile}
Print a link map to the file @var{mapfile}. See the description of the
@option{-M} option, above.
@@ -1463,8 +1473,8 @@ command line. Library directories specified in linker scripts
(including linker scripts specified on the command line) are ignored.
@ifclear SingleFormat
-@kindex --oformat
-@item --oformat @var{output-format}
+@kindex --oformat=@var{output-format}
+@item --oformat=@var{output-format}
@command{ld} may be configured to support more than one kind of object
file. If your @command{ld} is configured this way, you can use the
@samp{--oformat} option to specify the binary format for the output
@@ -1542,7 +1552,8 @@ but ignored.
@cindex retaining specified symbols
@cindex stripping all but some symbols
@cindex symbols, retaining selectively
-@item --retain-symbols-file @var{filename}
+@kindex --retain-symbols-file=@var{filename}
+@item --retain-symbols-file=@var{filename}
Retain @emph{only} the symbols listed in the file @var{filename},
discarding all others. @var{filename} is simply a flat file, with one
symbol name per line. This option is especially useful in environments
@@ -1559,9 +1570,9 @@ You may only specify @samp{--retain-symbols-file} once in the command
line. It overrides @samp{-s} and @samp{-S}.
@ifset GENERIC
-@item -rpath @var{dir}
+@item -rpath=@var{dir}
@cindex runtime library search path
-@kindex -rpath
+@kindex -rpath=@var{dir}
Add a directory to the runtime library search path. This is used when
linking an ELF executable with shared objects. All @option{-rpath}
arguments are concatenated and passed to the runtime linker, which uses
@@ -1587,8 +1598,8 @@ the @option{-rpath} option.
@ifset GENERIC
@cindex link-time runtime library search path
-@kindex -rpath-link
-@item -rpath-link @var{DIR}
+@kindex -rpath-link=@var{dir}
+@item -rpath-link=@var{dir}
When using ELF or SunOS, one shared library may require another. This
happens when an @code{ld -shared} link includes a shared library as one
of the input files.
@@ -1656,8 +1667,10 @@ and SunOS platforms. On SunOS, the linker will automatically create a
shared library if the @option{-e} option is not used and there are
undefined symbols in the link.
-@item --sort-common [= ascending | descending]
@kindex --sort-common
+@item --sort-common
+@itemx --sort-common=ascending
+@itemx --sort-common=descending
This option tells @command{ld} to sort the common symbols by alignment in
ascending or descending order when it places them in the appropriate output
sections. The symbol alignments considered are sixteen-byte or larger,
@@ -1665,24 +1678,24 @@ eight-byte, four-byte, two-byte, and one-byte. This is to prevent gaps
between symbols due to alignment constraints. If no sorting order is
specified, then descending order is assumed.
-@kindex --sort-section name
-@item --sort-section name
+@kindex --sort-section=name
+@item --sort-section=name
This option will apply @code{SORT_BY_NAME} to all wildcard section
patterns in the linker script.
-@kindex --sort-section alignment
-@item --sort-section alignment
+@kindex --sort-section=alignment
+@item --sort-section=alignment
This option will apply @code{SORT_BY_ALIGNMENT} to all wildcard section
patterns in the linker script.
@kindex --split-by-file
-@item --split-by-file [@var{size}]
+@item --split-by-file[=@var{size}]
Similar to @option{--split-by-reloc} but creates a new output section for
each input file when @var{size} is reached. @var{size} defaults to a
size of 1 if not given.
@kindex --split-by-reloc
-@item --split-by-reloc [@var{count}]
+@item --split-by-reloc[=@var{count}]
Tries to creates extra sections in the output file so that no single
output section in the file contains more than @var{count} relocations.
This is useful when generating huge relocatable files for downloading into
@@ -1699,7 +1712,7 @@ many relocations. @var{count} defaults to a value of 32768.
Compute and display statistics about the operation of the linker, such
as execution time and memory usage.
-@kindex --sysroot
+@kindex --sysroot=@var{directory}
@item --sysroot=@var{directory}
Use @var{directory} as the location of the sysroot, overriding the
configure-time default. This option is only supported by linkers
@@ -1720,8 +1733,8 @@ full debugging information by over 30 percent. Unfortunately, the SunOS
trouble). The @samp{--traditional-format} switch tells @command{ld} to not
combine duplicate entries.
-@kindex --section-start @var{sectionname}=@var{org}
-@item --section-start @var{sectionname}=@var{org}
+@kindex --section-start=@var{sectionname}=@var{org}
+@item --section-start=@var{sectionname}=@var{org}
Locate a section in the output file at the absolute
address given by @var{org}. You may use this option as many
times as necessary to locate multiple sections in the command
@@ -1732,18 +1745,18 @@ for compatibility with other linkers, you may omit the leading
should be no white space between @var{sectionname}, the equals
sign (``@key{=}''), and @var{org}.
-@kindex -Tbss @var{org}
-@kindex -Tdata @var{org}
-@kindex -Ttext @var{org}
+@kindex -Tbss=@var{org}
+@kindex -Tdata=@var{org}
+@kindex -Ttext=@var{org}
@cindex segment origins, cmd line
-@item -Tbss @var{org}
-@itemx -Tdata @var{org}
-@itemx -Ttext @var{org}
-Same as --section-start, with @code{.bss}, @code{.data} or
+@item -Tbss=@var{org}
+@itemx -Tdata=@var{org}
+@itemx -Ttext=@var{org}
+Same as @option{--section-start}, with @code{.bss}, @code{.data} or
@code{.text} as the @var{sectionname}.
-@kindex -Ttext-segment @var{org}
-@itemx -Ttext-segment @var{org}
+@kindex -Ttext-segment=@var{org}
+@item -Ttext-segment=@var{org}
@cindex text segment origin, cmd line
When creating an ELF executable or shared object, it will set the address
of the first byte of the text segment.
@@ -1789,7 +1802,7 @@ the linker script being used by the linker.
@kindex --version-script=@var{version-scriptfile}
@cindex version script, symbol versions
-@itemx --version-script=@var{version-scriptfile}
+@item --version-script=@var{version-scriptfile}
Specify the name of a version script to the linker. This is typically
used when creating shared libraries to specify additional information
about the version hierarchy for the library being created. This option
@@ -1949,8 +1962,8 @@ Second, don't forget to use @option{-Wl,-no-whole-archive} 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.
-@kindex --wrap
-@item --wrap @var{symbol}
+@kindex --wrap=@var{symbol}
+@item --wrap=@var{symbol}
Use a wrapper function for @var{symbol}. Any undefined reference to
@var{symbol} will be resolved to @code{__wrap_@var{symbol}}. Any
undefined reference to @code{__real_@var{symbol}} will be resolved to