C User's Guide | ![]() ![]() ![]() ![]() ![]() |
Incremental Link Editor (
ild
)This chapter describes
ild
,ild
-specific features, example messages, andild
options. This chapter is organized into the following sections:
- Introduction
- Overview of Incremental Linking
- How to Use ild
- How ild Works
- What ild Cannot Do
- Reasons for Full Relinks
- ild Options
- Environment
- Notes
Introduction
ild
is an incremental version of the Link Editorld
, and replacesld
for linking programs. Useild
to complete the edit, compile, link, and debug loop efficiently and more quickly. You can avoid relinking entirely by using the fix and continue feature of dbx which allows you to work without relinking. However, if you need to relink, the process can be faster if you useild
. For more information on fix and continue, see Chapter 11 in Debugging a Program Withdbx
.
ild
links incrementally so you can insert modified object code into an executable file that you created earlier, without relinking unmodified object files. The time required to relink depends upon the amount of code modified. Linking your application on every build does not require the same amount of time; small changes in code can be relinked very quickly.On the initial link,
ild
requires about the same amount of time thatld
requires, but subsequentild
links can be much faster than anld
link. The cost of the reduced link time is an increase in the size of the executable.Overview of Incremental Linking
When you use
ild
in place ofld
, the initial link causes the various text, data, bss, exception table sections, etc., to be padded with additional space for future expansion (see FIGURE 5-1). Additionally, all relocation records and the global symbol table are saved into a new persistent state region in the executable file. On subsequent incremental links,ild
uses timestamps to determine which object files have changed and patches the changed object code into a previously built executable. That is, previous versions of the object files are invalidated and the new object files are loaded into the space vacated, or into the pad sections of the executable when needed. All references to symbols in invalidated object files are patched to point to the correct new object files.
ild
does not support allld
command options. Ifild
is passed a command option that it does not support,ild
directly invokes /usr
/ccs
/bin
/ld
to perform the link. See Notes for more information on commands that are not supported by the Incremental Linker.How to Use
ild
ild
is invoked automatically by the compilation system in place ofld
under certain conditions. When you invoke a compilation system, you are invoking a compiler driver. When you pass certain options to the driver, the driver usesild
. The compiler driver reads the options from the command line and executes various programs in the correct order and adds files from the list of arguments that are passed.For example,
cc
first runsacomp
(the front-end of the compiler), thenacomp
runs the optimizing code generator, thencc
does the same thing for the other source files listed on the command line. The driver can then generate a call to eitherild
orld
, depending on the options, passing it all of the files just compiled, plus other files and libraries needed to make the program completeThe following figures shows an example of incremental linking.
FIGURE 5-1 An Example of Incremental Linking![]()
The following compilation system options control whether a link step is performed by
ild
orld
:
-xildon
- Always useild
-xildoff
- Always useld
Note If-xildon
and-xildoff
are both present, the last command listed is used by the linker.
-g
- When neither-xildoff
or-G
are given, useild
for link-only invocations (no source files on the command line). For a complete explanation of-g
, see -g.-G
- Prevents the-g
option from having any effect on linker selection. For a complete explanation of-G
, see -G.When you use the
-g
option to invoke debugging, and you have the default Makefile structure (which includes compile-time options such as-g
on the link command line), you useild
automatically when doing development.How
ild
WorksOn an initial link,
ild
saves information about:
- All of the object files looked at.
- The symbol table for the executable produced.
- All symbolic references not resolved at compile time.
Initial
ild
links take about as much time as anld
link.
- Determines which files have changed.
- Relinks the modified object files.
- Uses stored information to modify changed symbolic references in the rest of the program.
Incremental
ild
links are much faster thanld
links.In general, you do one initial link and all subsequent links are incremental.
For example,
ild
saves a list of all places where symbolfoo
is referenced in your code. If you do an incremental link that changes the value offoo
,ild
must change the value of all references tofoo
.
ild
spreads out the components of the program and each section of the executable has padding added to it. Padding makes the executable modules larger than when they were linked byld
. As object files increase in size during successive incremental links, the padding can become exhausted. If this occurs,ild
displays a message and does a complete full relink of the executable.For example, as FIGURE 5-1 shows, each of the three columns shows the sequence of text and data in a linked executable program. The left column shows text and data in an executable linked by
ld
. The center column shows the addition of text and data padding in an executable linked byild
. Assume that a change is made to the source file for Text 1 that causes the Text section to grow without affecting the size of the other sections. The right column shows that the original location of Text 1 has been replaced by Text padding (Text 1 has been invalidated). Text 1 has been moved to occupy a portion of the Text padding space.To produce a smaller nonincremental executable, run the compiler driver (for example,
cc
orCC
) with the-xildoff
option, andld
is invoked to produce a more compact executable.The resulting executable from
ild
can be debugged bydbx
becausedbx
/Debugger understands the padding thatild
inserts between programs.For any command-line option that
ild
does not understand,ild
invokesld
.ild
is compatible withld
(in /usr
/ccs
/bin
/ld
). See ild Options, for details.There are no special or extra files used by
ild
.What
ild
Cannot DoWhen
ild
is invoked to create shared objects,ild
invokesld
to create the link.Performance of
ild
may suffer greatly if you change a high percentage of object files.ild
automatically does an full relink when it detects that a high percentage of files have been changed.Do not use
ild
to produce the final production code for shipment.ild
makes the file larger because parts of the program have been spread out due to padding. Because of the padding and additional time required to link, it is recommended that you do not use the-xildon
option for production code. (Use-xildoff
on the link line if-g
is present.)
ild
may not link small programs much faster, and the increase in size of the executable is greater than that for larger programs.Third-party tools that work on executables may have unexpected results on
ild
-produced binaries.Any program that modifies an executable, for example
strip
ormcs
, might affect the ability ofild
to perform an incremental link. When this happens,ild
issues a message and performs a full relink. For more information on a full relink, see Reasons for Full Relinks.Reasons for Full Relinks
The following section explains under which circumstances
ild
callsld
to complete a link.
ild
Deferred-Link MessagesThe message
`ild: calling ld to finish link' . . .
means thatild
cannot complete the link, and is deferring the link request told
for completion. By default, these messages are displayed as needed. You can suppress these messages by using the-z
i_quiet
option.The following message is suppressed if
ild
is implicitly requested (-g
), but is displayed if-xildon
is on the command line. This message is displayed in all cases if you use the-z
i_verbose
option, and never displayed if you use the-z
i_quiet
option.
ild: calling ld to finish link --
cannot handle shared libraries in archive
library nameHere are further examples of
-z
i_verbose
messages:
ild:
calling
ld
to
finish
link
--cannot
handle
keyword
Keyword
ild:
calling
ld
to
finish
link
--cannot
handle
-d
Keyword
ild:
calling
ld
to
finish
link
--cannot
handle
-z
keyword
ild:
calling
ld
to
finish
link
--cannot
handle
argument
keyword
ild
Relink MessagesThe message `
ild: (Performing full relink)
' . . . means that for some reasonild
cannot do an incremental link and must do a full relink. This is not an error. It is to inform you that this link will take longer than an incremental link (see How ild Works, for more details).ild
messages can be controlled byild
options-z
i_quiet
and-z
i_verbose
. Some messages have a verbose mode with more descriptive text.You can suppress all of these messages by using the
ild
option-z
i_quiet.
If the default message has a verbose mode, the message ends with an ellipsis ([...]
) indicating more information is available. You can view the additional information by using the-z
i_verbose
option. Example messages are shown with the-z
i_verbose
option selected.Example 1:
internal
free
space
exhausted
The most common of the full relink messages is the
internal free space exhausted
message:
These commands show that going from a one-line compile to a two-line compile causes debugging information to grow in the executable. This growth causes
ild
to run out of space and do an full relink.Example 2: Running
strip
Another problem arises when you run
strip
. Continuing from Example 1:
Example 3:
ild
versionWhen a new version of
ild
is run on an executable created by an older version ofild
, you see the following error message:
Note The numbers (2/16) are used only for internal reporting.
Example 4:
too
many
files
changed
Sometimes
ild
determines that it will be faster to do a full relink than an incremental link. For example:
Here, use of the
touch
command causesild
to determine that filesx0.o
throughx8.o
have changed and that a full relink will be faster than incrementally relinking all nine object files.Example 5:
full
relink
There are certain conditions that can cause a full relink on the next link, as compared to the previous examples that cause a full relink on this link.
The next time you try to link that program, you see the message:
# ild detects previous error and does a full relink$
cc -xildon
-z
i_verbose
broken.o
ild: (Performing full relink) cannot do incremental relink due to problems in the previous link
Example 6: New working directory
ild
OptionsThis section describes the linker control options directly accepted by the compilation system and linker options that may be passed through the compilation system to
ild
.
-a
In static mode only, produce an executable object file; give errors for undefined references. This is the default behavior for static mode.
-B
dynamic
|
static
Options governing library inclusion. Option
-Bdynamic
is valid in dynamic mode only. These options can be specified any number of times on the command line as toggles: if the-Bstatic
option is given, no shared objects are accepted until -Bdynamic
is seen. See option -lx.
-d y|n
When
-dy
(the default) is specified,ild
uses dynamic linking; when-dn
is specified,ild
uses static linking. See option -B dynamic | static.
-e epsym
Set the entry point address for the output file to be that of the symbol
epsym
.
-g
The compilation systems invoke
ild
in place ofld
when the-g
option (output debugging information) is given, unless any of the following are true:
- The
-G
option (produce a shared library) is given- The
-xildoff
option is present- Any source files are named on the command line
-I
nameWhen building an executable, use name as the path name of the interpreter to be written into the program header. The default in static mode is no interpreter; in dynamic mode, the default is the name of the runtime linker,
/usr/lib/ld.so.1
. Either case may be overridden by-I
name.exec
only loads this interpreter when it loadsa.out
and will pass control to the interpreter rather than toa.out
directly.
-i
Ignores
LD_LIBRARY_PATH
setting. This option is useful when anLD_LIBRARY_PATH
setting is in effect to influence the runtime library search, which would interfere with the link editing being performed. (This also applies to the setting ofLD_LIBRARY_PATH_64
).
-L
pathAdds path to the library search directories.
ild
searches for libraries first in any directories specified by the-L
options, and then in the standard directories. This option is useful only if it precedes the-l
options to which it applies on the command line. You can use the environment variableLD_LIBRARY_PATH
andLD_LIBRARY_PATH_64
to supplement the library search path (see LD_LIBRARY_PATH).
-l
xSearches a library
libx.so
orlibx.a
, the conventional names for shared object and archive libraries, respectively. In dynamic mode, unless the-Bstatic
option is in effect,ild
searches each directory specified in the library search path for a filelibx
.so
orlibx
.a
. The directory search stops at the first directory containing either.ild
chooses the file ending in .so
if-l
expands to two files whose names are of the formlibx
.so
andlibx
.a
. If nolibx
.so
is found, thenild
acceptslib
x.a
. In static mode, or when the-Bstatic
option is in effect,ild
selects only the file ending in .a
. A library is searched when its name is encountered, so the placement of-l
is significant.
-m
Produce a memory map or listing of the input/output sections on the standard output.
-o
outfileProduces an output object file named outfile. The name of the default object file is
a.out
.
-Q
y|n
Under
-Qy
, anident
string is added to the .comment
section of the output file to identify the version of the link editor used to create the file. This results in multipleld
idents
when there have been multiple linking steps, such as when usingld
-r
. This is identical with the default action of thecc
command. Option-Qn
suppresses version identification.
-R
pathThis option gives a colon-separated list of directories that specifies library search directories to the runtime linker. If present and not null, path is recorded in the output object file and passed to the runtime linker. Multiple instances of this option are concatenated and separated by a colon.
-s
Strips symbolic information from the output file. Any debugging information and associated relocation entries are removed. Except for relocatable files or shared objects, the symbol table and string table sections are also removed from the output object file.
-t
Turn off the warning about multiply defined symbols that are not the same size.
-u
symnameEnter symname as an undefined symbol in the symbol table.This is useful for loading entirely from an archive library, since initially the symbol table is empty and an unresolved reference is needed to force the loading of the first routine. The placement of this option on the command line is significant; it must be placed before the library that defines the symbol.
-V
Output a message about the version of
ild
being used.
-xildoff
Incremental linker off. Force the use of bundled
ld
. This is the default if-g
is not being used, or-G
is being used. You can override this default with-xildon
.
-xildon
Incremental linker. Force the use of
ild
in incremental mode. This is the default if-g
is being used. You can override this default with-xildoff
.
-YP,
dirlist(
cc
only) Changes the default directories used for finding libraries. Option dirlist is a colon-separated path list.
Note ild
uses the-z
name form for special options. The i_ prefix to the-z
options identifies those options peculiar toild
.
-z allextract|defaultextract|weakextract
Alter the extraction criteria of objects from any archives that follow. By default archive members are extracted to satisfy undefined references and to promote tentative definitions with data definitions. Weak symbol references do not trigger extraction. Under
-z
allextract
, all archive members are extracted from the archive. Under-z
weakextract
, weak references trigger archive extraction. -zdefaultextract
provides a means of returning to the default following use of the former extract options.
-z
defs
Forces a fatal error if any undefined symbols remain at the end of the link. This is the default when building an executable. It is also useful when building a shared object to assure that the object is self-contained, that is, that all its symbolic references are resolved internally.
-z
i_dryrun
(
ild
only.) Prints the list of files that would be linked byild
and exits.
-z
i_full
(
ild
only.) Does a complete relink in incremental mode.
-z
i_noincr
(
ild
only.) Runsild
in nonincremental mode (not recommended for customer use -- used for testing only).
-z
i_quiet
(
ild
only) Turns off all ild relink messages.
-z
i_verbose
(
ild
only) Expands on default information on someild
relink messages.
-z
nodefs
Allows undefined symbols. This is the default when building a shared object. When used with executables, the behavior of references to such "undefined symbols" is unspecified.
Options Passed to
ild
from the Compilation SystemThe following options are accepted by ild, but you must use the form:
-Wl,
arg,
arg (forcc
), or-Qoption
ld
arg,
arg (for others), to pass them toild
via the compilation system
-a
In static mode only, produces an executable object file; gives errors for undefined references. This is the default behavior for static mode. Option
-a
cannot be used with the-r
option.
-m
Produces a memory map or listing of the input/output sections on the standard output.
-
t
Turn off the warning about symbols that are defined more than once and that are not the same size.
-e
epsym
Sets the entry point address for the output file to be that of the symbol
epsym
.
-I
nameWhen building an executable, uses name as the path name of the interpreter to be written into the program header. The default in static mode is no interpreter; in dynamic mode, the default is the name of the runtime linker, /
usr
/lib
/ld
.so
.1
. Either case can be overridden by-I
name. Theexec
system call loads this interpreter when it loads thea.out
and passes control to the interpreter rather than to thea.out
directly.
-u
symnameEnters symname as an undefined symbol in the symbol table. This is useful for loading entirely from an archive library because, initially, the symbol table is empty and an unresolved reference is needed to force the loading of the first routine. The placement of this option on the command line is significant; it must be placed before the library that defines the symbol.
Environment
A list of directories which is searched for the libraries that are specified with the
-l
option. Multiple directories are separated by a colon. In the most general case, it contains two directory lists separated by a semicolon:
dirlist1;
dirlist2
If
ild
is called with any number of occurrences of-L
, as in:
ild
...-Lpath1 ... -Lpathn ...
then the search path ordering is:
dirlist1 path1 ... pathn dirlist2LIBPATH
When the list of directories does not contain a semicolon, it is interpreted as follows:
dirlist2
LD_LIBRARY_PATH
is also used to specify library search directories to the runtime linker. That is, ifLD_LIBRARY_PATH
exists in the environment, the runtime linker searches the directories named in it, before its default directory, for shared objects to be linked with the program at execution.
Note When running aset-user-ID
orset-group-ID
program, the runtime linker searches only for libraries in/usr/lib
. It also searches for any full pathname specified within the executable. A full pathname is the result of a runpath being specified when the executable was constructed. Any library dependencies specified as relative pathnames are silently ignored.
On Solaris 7 and Solaris 8, this environment variable is similar to
LD_LIBRARY_PATH
but overrides it when searching for 64-bit dependencies.When you run Solaris 7 or Solaris 8 on a
SPARC
processor and link in 32-bit mode,LD_LIBRARY_PATH_64
is ignored. If onlyLD_LIBRARY_PATH
is defined, it is used for both 32-bit and 64-bit linking. If bothLD_LIBRARY_PATH
andLD_LIBRARY_PATH_64
are defined, the 32-bit linking will be done usingLD_LIBRARY_PATH
and the 64-bit linking will be done usingLD_LIBRARY_PATH_64
.LD_OPTIONSA default set of options to
ild
.LD_OPTIONS
is interpreted byild
as though its value had been placed on the command line immediately following the name used to invokeild
, as in:
ild
$LD_OPTIONS
... other-arguments ...
A list of shared objects that are to be interpreted by the runtime linker. The specified shared objects are linked in after the program being executed and before any other shared objects that the program references.
Note When running aset-user-ID
orset-group-ID
program, this option is silently ignored.
An alternative mechanism for specifying a runpath to the link editor (see the
-R
option). If bothLD_RUN_PATH
and the-R
option are specified, the-R
is used.(not supported by
ild
) Provide a list of tokens that cause the runtime linker to print debugging information to the standard error. The special token help indicates the full list of tokens available.
Note Environment variable names beginning with the characters `LD_
` are reserved for possible future enhancements told
. Environment variable-names beginning with the characters `ILD_
` are reserved for possible future enhancements toild
.
Notes
If
ild
determines that a command line option is not implemented,ild
directly invokes /usr
/css
/bin
/ld
to perform the link.
ld
Options Not Supported byild
The following options, which may be given to the compilation system, are not supported by
ild
.
-B
symbolic
In dynamic mode only, when building a shared object, bind references to global symbols to their definitions within the object, if definitions are available. Normally, references to global symbols within shared objects are not bound until runtime, even if definitions are available, so that definitions of the same symbol in an executable or other shared objects can override the object's own definition.
ld
issues warnings for undefined symbols unless-z
defs overrides.
-b
In dynamic mode only, when creating an executable, does not do special processing for relocations that reference symbols in shared objects. Without the
-b
option, the link editor creates special position-independent relocations for references to functions defined in shared objects and arranges for data objects defined in shared objects to be copied into the memory image of the executable by the runtime linker. With the-b
option, the output code can be more efficient, but it is less sharable.
-G
In dynamic mode only, produces a shared object. Undefined symbols are allowed.
-h
nameIn dynamic mode only, when building a shared object, records name in the object's dynamic section. Option name is recorded in executables that are linked with this object rather than the object's UNIX System file name. Accordingly, name is used by the runtime linker as the name of the shared object to search for at runtime.
-z
muldefs
Allows multiple symbol definitions. By default, multiple symbol definitions occurring between relocatable objects result in a fatal error condition. This option suppresses the error condition and allows the first symbol definition to be taken.
-z
text
In dynamic mode only, forces a fatal error if any relocations against non-writable, allocatable sections remain.
Additional Unsupported Commands
In addition, the following options that may be passed directly to
ld
, are not supported byild
:
-D
token,
token,...
Prints debugging information as specified by each token, to the standard error. The special token help indicates the full list of tokens available.
-
F
nameUseful only when building a shared object. Specifies that the symbol table of the shared object is used as a "filter" on the symbol table of the shared object specified by name.
-M
mapfileReads mapfile as a text file of directives to
ld
. See SunOS 5.3 Linker and Libraries Manual for a description of mapfiles.
-r
Combines relocatable object files to produce one relocatable object file.
ld
does not complain about unresolved references. This option cannot be used in dynamic mode or with-a
.Files That
ild
Uses
lib
x .a
librariesa.out
output fileLIBPATH
usually /usr
/lib
Sun Microsystems, Inc. Copyright information. All rights reserved. Feedback |
Library | Contents | Previous | Next | Index |