Man Page ild.1
NAME
ild - incremental link editor (ild) for object files
SYNOPSIS
ild [ -a ] [ -i ] [ -m ] [ -s ] [ -t ]
[ -V ] [ -B dynamic|static ] [ -d y|n ]
[ -e epsym ] [ -I name ] [ -L path ] [ -l x ]
[ -o outfile ] [ -Q y|n ] [ -R path ] [ -u symname ]
[ -Y P,dirlist ]
[ -z allextract|defaultextract|weakextract ]
[ -z defs|nodefs ] [ -z i_dryrun ]
[ -z i_full ] [ -z i_noincr ] [ -z i_quiet ]
[ -z i_verbose ]
filename ...
DESCRIPTION
ild links incrementally so you can insert modified object
code into an executable built previously. The time required
to link depends upon the amount of code changed. Linking
your application on every build does not require the same
amount of time; small changes in code can be linked very
quickly.
The ild command combines relocatable object files, performs
relocation, and resolves external symbols. ild operates in
two modes, static or dynamic, as governed by the -d option.
In static mode, -dn, relocatable object files given as argu-
ments are combined to produce an executable object file. In
dynamic mode, -dy, the default, relocatable object files
given as arguments are combined to produce an executable
object file that will be linked at execution with any shared
object files given as arguments. In all cases, the output
of ild is left in a.out by default.
If any argument is a library, it is searched exactly once at
the point it is encountered in the argument list. The
library may be either a relocatable archive or a shared
object. For an archive library, only those routines defin-
ing an unresolved external reference are loaded. The
archive library symbol table (see ar(4)) is searched sequen-
tially with as many passes as are necessary to resolve
external references that can be satisfied by library
members. Thus, the ordering of members in the library is
functionally unimportant, unless there exist multiple
library members defining the same external symbol. A shared
object consists of a single entity all of whose references
must be resolved within the executable being built or within
other shared objects with which it is linked.
The compilation system options that control whether a link
step is performed by ild or ld are: -xildon, always use ild;
-xildoff, always use ld (if -xildon and -xildoff are both
present, the last governs); -g, when neither -xildoff or -G
are given, use ild for link-only invocations (no source
files on the command line); -G, prevents the -g option from
having any effect on linker selection.
Note: Both -g and -G have other meanings that are documented
as part of the compilation systems.
When you use the -g option to invoke ild, and you have the
default Makefile structure (which includes compile-time
options such as -g on the command line for the link step),
you use ild automatically when doing development.
If ild determines that an ild option is unimplemented (see
NOTES), ild directly invokes /usr/css/bin/ld to perform the
link.
OVERVIEW OF INCREMENTAL LINKING
In incremental mode, the initial link causes the various
text, data, bss, exception table sections, etc., to be pad-
ded with additional space for future expansion. Addition-
ally, all relocation records, ranlib indices, and the global
symbol table are saved by ild in the executable file.
On subsequent incremental links, ild uses timestamps to dis-
cover which object files have changed and patches the
changed object code into a previously built executable.
That is, the previous versions of the object files are
invalidated and the new object files are loaded into the pad
sections of the executable. All references to symbols in
invalidated object files are patched to point to the correct
new object files.
OPTIONS
-a In static mode only, produce an executable
object file; give errors for undefined refer-
ences. This is the default behavior for static
mode.
-i Ignore LD_LIBRARY_PATH setting. This option is
useful when an LD_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 set-
ting of LD_LIBRARY_PATH_64 )
-m Produce a memory map or listing of the
input/output sections on the standard output.
(See BUGS.)
-s Strip symbolic information from the output file.
Any debugging information, that is .debug,
.line, and .stab sections and their associated
relocation entries, will be removed. Except for
relocatable files or shared objects, the symbol
table and string table sections will also be
removed from the output object file.
-t Turn off the warning about multiply defined sym-
bols that are not the same size.
-V Output a message giving information about the
version of ild being used.
-B dynamic|static
Options governing library inclusion. -Bdynamic
is valid in dynamic mode only. These options
may be specified any number of times on the com-
mand line as toggles: if the -Bstatic option is
given, no shared objects will be accepted until
-Bdynamic is seen. See also the -l option.
-d y|n When -dy, the default, is specified, ild uses
dynamic linking; when -dn is specified, ild uses
static linking. Also see -B dynamic|static.
-e epsym Set the entry point address for the output file
to be that of the symbol epsym.
-I name When 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 -Iname. exec will load this interpreter when
it loads the a.out and will pass control to the
interpreter rather than to the a.out directly.
-L path Add 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. The environment
variables LD_LIBRARY_PATH and LD_LIBRARY_PATH_64
may be used to supplement the library search
path (see ENVIRONMENT below).
-l x Search a library libx.so or libx.a, the conven-
tional 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 file libx.so or libx.a. The
directory search stops at the first directory
containing either. ild chooses the file ending
in .so if -lx expands to two files whose names
are of the form libx.so and libx.a. If no
libx.so is found, then ild accepts libx.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 encoun-
tered, so the placement of -l is significant.
-o outfile Produce an output object file named outfile.
The name of the default object file is a.out.
-Q y|n Under -Qy, an ident string is added to the .com-
ment section of the output file to identify the
version of the link editor used to create the
file. This will result in multiple ld idents
when there have been multiple linking steps,
such as when using ld -r. This is identical
with the default action of the cc command. -Qn
suppresses version identification.
-R path A colon-separated list of directories that
specifies library search directories to the run-
time 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.
-u symname Enter symname as an undefined symbol in the sym-
bol table. This is useful for loading entirely
from an archive library, since initially the
symbol table is empty and an unresolved refer-
ence 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 will define the symbol.
-Y P,dirlist
Change the default directories used for finding
libraries. dirlist is a colon-separated path
list.
NOTE: The "-z name" form is used by ild for spe-
cial options. The "-i_" prefix to the -z
options identifies those options peculiar to
ild.
-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. -z defaultextract
provides a means of returning to the default
following use of the former extract options.
-z defs Force 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 inter-
nally.
-z nodefs Allow 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.
-z i_dryrun (ild only). Print the list of files ild would
have linked and exit.
-z i_full (ild only). Do a complete relink in incremental
mode.
-z i_noincr (ild only). Run ild in non-incremental mode
(not recommended for customer use - used for
testing only).
-z i_quiet (ild only). Turns off these two ild messages:
`ild: (Performing full relink) ...' and `ild:
calling ld to finish link'.
-z i_verbose
(ild only). Expands on default information in
these two ild messages: `ild: (Performing full
relink) ...' and `ild: calling ld to finish
link' whenever the default text ends with
`[...]'.
ENVIRONMENT
LD_LIBRARY_PATH
A list of directories in which to search for libraries
specified with the -l option. Multiple directories are
separated by a colon. In the most general case, it
will contain two directory lists separated by a semi-
colon:
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 dirlist2 LIBPATH
When the list of directories does not contain a semi-
colon, it is interpreted as dirlist2.
LD_LIBRARY_PATH is also used to specify library search
directories to the runtime linker. That is, if
LD_LIBRARY_PATH exists in the environment, the runtime
linker will search the directories named in it, before
its default directory, for shared objects to be linked
with the program at execution.
Note: When running a set-user-ID or set-group-ID pro-
gram, the runtime linker will only search for libraries
in /usr/lib and any full pathname specified within the
executable as a result of a runpath being specified
when the executable was constructed. Any library
dependencies specified as relative pathnames will be
silently ignored.
LD_LIBRARY_PATH_64
On Solaris 7, this environment variable is similar to
LD_LIBRARY_PATH but overrides it when searching for
64-bit dependencies.
When running Solaris 7 on a SPARC processor and linking
in 32-bit mode, LD_LIBRARY_PATH_64 is ignored. If only
LD_LIBRARY_PATH is defined, it us used for both 32-bit
and 64-bit linking. If both LD_LIBRARY_PATH and
LD_LIBRARY_PATH_64 are defined, the 32-bit linking will
be done using LD_LIBRARY_PATH and the 64-bit linking
using LD_LIBRARY_PATH_64 .
See Linker and Libraries Guide for more information on
these environment variables.
LD_OPTIONS
A default set of options to ild . LD_OPTIONS is
interpreted by ild just as though its value had been
placed on the command line, immediately following the
name used to invoke ild , as in:
ild $LD_OPTIONS ... other-arguments ...
LD_PRELOAD
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 a set-user-ID or set-group-ID pro-
gram, this option is silently ignored.
LD_RUN_PATH
An alternative mechanism for specifying a runpath to
the link editor (see -R option). If both LD_RUN_PATH
and the -R option are specified, -R supersedes.
LD_DEBUG
(not supported by ild) Provide a list of tokens that
will cause the runtime linker to print debugging infor-
mation to the standard error. The special token help
indicates the full list of tokens available.
Note: Environment variable-names beginning with the charac-
ters `LD_' are reserved for possible future enhancements to
ld. Environment variable-names beginning with the charac-
ters `ILD_' are reserved for possible future enhancements to
ild.
NOTES
If ild determines that an ild option is unimplemented, ild
directly invokes /usr/css/bin/ld to perform the link.
The following ld options are not supported by ild at this
time:
-b
-G
-B symbolic
-D token
-F name
-h name
-M mapfile
-z muldefs
-z text
BUGS
ild uses the timestamp associated with an archive library
object file to determine which files have been updated. If
multiple definitions of the same symbol do not exist in the
library, ild finds the correct (that is, only) symbol. How-
ever, multiple definitions of the same symbol confuse ild.
ild occasionally silently handles multiple definitions
incorrectly.
Option -m produces a memory map but not a listing of the
nonfatal multiply-defined symbols on the standard output.
Once an object file is extracted from an archive file and
linked into an incremental executable, that object file
remains in the executable, even if all references to it are
removed, until the next complete relink (which can be forced
by deleting the binary).
FILES
libx.a libraries
a.out output file
LIBPATH usually /usr/ccs/lib:/usr/lib
SEE ALSO
cc(1), CC(1), ld(1), exec(2), elf(3E), end(3C), a.out(4),
ar(4) f77(1)
Linker and Libraries Guide
Sun WorkShop: C User's Guide manual