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 defs|nodefs ] [ -z i_dryrun ]
[ -z i_full ] [ -z i_noincr ] [ -z i_quiet ]
[ -z i_verbose ]
filename ...

DESCRIPTION

ild runs under the Solaris 2.2 or later operating environment.

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 arguments 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 defining an unresolved external reference are loaded. The archive library symbol table (see ar(4)) is searched sequentially 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 padded with additional space for future expansion. Additionally, all relocation records, ranlib indices, and the global symbol table are saved by ild. On Solaris 2.2 or later, the saved items are kept in the executable file.

On subsequent incremental links, ild uses timestamps to discover 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 references. 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.

-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 symbols 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 command 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 variable LD_LIBRARY_PATH may be used to supplement the library search path (see LD_LIBRARY_PATH below).

-l x
    Search a library libx.so or libx.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 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 encountered, 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 .comment 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 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.

-u symname
    Enter 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 will define the symbol.