ld_pa(1) General Commands Manual ld_pa(1)
NAME
ld_pa: ld - link editor for PA-RISC systems
SYNOPSIS
Common Options
search] filename] epsym] symbol]... x | file]... library] outfile] symbol]... symbol]... bind] offset] lib] dir]... offset] file]
file] func_sym_x=func_sym_y]... path_list] file] symbol] symbol] shared_library_path] function] size] internal_name] function]
file] shared_library_path] size] name] size] size] flag] symbol] dir] n] size]
PA-RISC 32-Bit (SOM) Options
name] n] oldpath:newpath] pathname] filename] size] flag]
PA-RISC 64-Bit (ELF) Options
filename] bucketsizetype] symbol]... percentage] symbol]... symbol]... pagesize] pagesize] type]
Remarks
This manpage describes on PA-RISC systems. For on Integrity systems, see ld_ia(1).
DESCRIPTION
takes one or more object files or libraries as input and combines them to produce a single (usually executable) file. In doing so it
resolves references to external symbols, assigns final addresses to procedures and variables, revises code and data to reflect new
addresses (a process called "relocation"), and updates symbolic debug information when present in the file.
By default, produces an executable file that can be run by the HP-UX loader (see exec(2)). Alternatively, the linker can generate a relo-
catable file that is suitable for further processing by (see below). It can also generate a shared library (see below). The linker marks
the output file non-executable if there are any duplicate symbols or any unresolved external references remain.
may or may not generate an output file (see option) if any other errors occur during its operation.
recognizes three kinds of input files:
o Object files created by the compilers, assembler, or linker (also known as files),
o Shared libraries created by the linker, and
o Archives of object files (called archive libraries).
An archive library contains a table of all the externally-visible symbols from its component object files. (The archiver command ar(1)
creates and maintains this index.) uses this table to resolve references to external symbols.
processes files in the same order as they appear on the command line. It includes code and data from an archive library element if and
only if that object module provides a definition for a currently unresolved reference within the user's program or shared library or depen-
dent shared library.
It is common practice to list libraries following the names of all simple object files on the command line.
Code and data from shared libraries is never copied into an executable program. The dynamic loader on 32-bit links is invoked at startup
time by the startup file if a program uses shared libraries. Identical copies of can be found in either or
For 64-bit mode, the dynamic loader is and is invoked by exec for those programs that use shared libraries. is not required in shared
bound links.
The dynamic loader attaches each required library to the process and resolves all symbolic references between the program and its
libraries.
NOTE: For information on linking secure programs with shared libraries, see the section below.
The text segment of a shared library is shared among all processes that use the library; each process using the library receives its own
copy of the data segment. If has been run on the executable that loads the library, the text segment of a shared library is mapped pri-
vately for each process running the executable. recursively examines the dependencies of shared libraries used by a program that was cre-
ated by If does not find a supporting shared library at the path recorded in the dependency list of a shared library, and if the dependency
is the result of an argument used when the shared library was created, will search all the directories that it would search for a library
that was specified with (see and
Environment Variables
Arguments can be passed to the linker through the environment variable as well as on the command line. The linker gets the value of and
places its contents before any arguments on the command line.
The environment variable defines the full execution path for the debug preprocessor The default value is invokes on its output file if that
file is executable and contains debug information. To defer invocation of until the first debug session, set to
The environment variable can be used to specify default directories to search for library files. See the option.
Common Options
The common options are listed first, followed by the options supported only in a 32-bit linker, and then the options only supported in a
64-bit linker.
Specify whether shared or archive libraries are searched
with the option. The value of search should be one of or This option can appear more than once, interspersed among
options, to control the searching for each library. The default is to use the shared version of a library if one is
available, or the archive version if not.
If either or is active, only the specified library type is accepted.
If is active, the archive form is preferred, but the shared form is allowed.
If is active, the shared form is preferred but the archive form is allowed.
Create a shared library rather than a normal executable file.
Object files processed with this option must contain (PIC). See the discussion of PIC in cc(1), CC(1) (part of the
optional C++ compiler documentation), f77(1), pc(1), as(1), and
Read options from a file. Each line contains zero or more arguments separated by white space. Each line in the file,
including the last line, must end with a newline character. A character implies that the rest of the line is a com-
ment. To escape a character, use the sequence
Force definition of "common" storage; that is, assign addresses and
sizes, for output. This option also strips COMDAT information from the output.
This allows the linker to create a program which can use shared libraries.
This is the default for 64-bit links unless is used. In 32-bit mode, the linker creates a static executable if there
are no shared libraries on the link line.
Set the default entry point address for the output file to be that of
the symbol epsym. (This option only applies to executable files.)
Prior to writing the symbol table to the output file,
mark this name as "local" so that it is no longer externally visible. This ensures that this particular entry will
not clash with a definition in another file during future processing by
More than one symbol can be specified, but must precede each one. If used when building a shared library or program,
this option prevents the named symbol from being visible to the dynamic loader.
Search a library
or where x is one or more characters. The current state of the option determines whether the archive or shared ver-
sion of a library is searched.
Because a library is searched when its name is encountered, the placement of a is significant. By default, 32-bit
libraries are located in and 64-bit libraries are located in
If the environment variable is present in the user's environment, it should contain a colon-separated list of direc-
tories to search. These directories are searched instead of the default directories, but options can still be used.
If a program uses shared libraries, the dynamic loader for 32-bit or for 64-bit will attempt to load each library
from the same directory in which it was found at link time (see the and options).
Search the library specified.
Similar to the option except the current state of the option is not important. The library name can be any valid
filename. (Note that previous releases required that the library name contain the prefix and end with a suffix of or
This option produces a load map on the standard output.
This option is accepted but ignored by the 64-bit
Generate an executable output file with file type This is the default. This option is incompatible with and
This option forces the linker to create a fully archive bound program.
Produce an output object file named
outfile if outfile is not specified).
This option is ignored for 64-bit links.
Generate an executable output file with file type This option is incompatible with and
Retain relocation information in the output file for subsequent re-linking.
The command does not report undefined symbols. This option cannot be used when building a shared library ( or in
conjunction with or incremental linking options.
Strip the output file of all symbol table, relocation,
and debug support information. This might impair or prevent the use of a symbolic debugger or a profiler on the
resulting program. This option is incompatible with (The strip(1) command also removes this information.) This
option is incompatible with (The incremental linking requires the parts of the output load module which are stripped
out with option.)
Print a trace (to standard output) of each input file as
processes it.
Enter symbol as an undefined symbol in the symbol table. The resulting unresolved reference is useful for linking a pro-
gram solely from object files in a library. More than one symbol can be specified, but each must be preceded by
Display verbose messages during linking.
On 32-bit systems, for each module loaded, the linker indicates which symbol caused that module to be loaded. For
64-bit systems, the linker indicates this information only for modules loaded from archive libraries.
Strip local symbols from the output file.
This reduces the size of the output file without impairing the effectiveness of object file utilities. This option
is incompatible with the option. This option is incompatible with the option. The incremental linking requires the
parts of the output load module which are stripped out with the option.
NOTE: Use of might affect the use of a debugger or profiler.
Indicate each file in which
symbol appears. More than one symbol can be specified, but each must be preceded by
Arrange for run-time dereferencing of null pointers to produce a
signal. (This is the complement of the option.)
Select run-time binding behavior of a program using shared libraries or
the binding preference in building a shared library. The most common values for bind are:
Create a direct link between symbol references and shared libraries by recording the name of the resolved shared
library during symbol resolution. This information is used during runtime to quickly resolve symbols without search-
ing through all currently loaded libraries.
implicitly turns on symbolic binding (see and disables dependent shared library processing.
Direct binding can be disabled during runtime by setting the environment variable.
Bind addresses on first reference
rather than at program start-up time. This is the default.
Mark the shared library so that it behaves as if loaded with
flag to This does not affect the dependent shared libraries.
NOTE: The binding mode is currently supported only for 64-bit applications.
Bind addresses of all symbols immediately upon loading the library.
Commonly followed by to allow procedure calls that cannot be resolved at program start-up to be resolved on
first reference.
Since suppresses messages about unresolved symbols, also specify to display those messages.
See the example below.
Only record direct bind information to shared libraries marked for
lazy loading. See
Mark the shared library so that an explicit unload using
or returns success silently without detaching the shared library from the process. Subsequently, the shared
library handle is valid only for It stays invalid for and until the next explicit load using or
Disallow direct binding.
Only a "direct hint" is recoreded for references to libraries marked for lazy loading. This is the default
behavior.
If also using
for code symbols that could not be bound at program startup, defer binding them until they are referenced.
See description of above.
Since suppresses messages about unresolved symbols, also specify to display those messages.
Causes the search for a symbol definition to be restricted to
those symbols that were visible when the library was loaded.
Used only when building a shared library (with the
option), this option causes all unresolved symbols inside a library to be resolved internally if possible. By
default, unresolved symbols are resolved to the most visible definition in the library or outside the library.
NOTE: Do not use this option while building shared libraries on Integrity systems. Use the option
Display verbose messages when binding symbols.
This is the default except when is specified. In that case, must be explicitly specified to get verbose mes-
sages.
See the option or the manual for more information on the uses of binding modes.
Set the origin (in hexadecimal) for the data segment.
When used with the option, if you change the offset after the initial incremental link, the linker performs an ini-
tial incremental link automatically.
Mark all symbols defined by a program for export
to shared libraries. In a 32-bit link or mode 64-bit link, marks only those symbols that are actually referenced by
a shared library seen at link time. In a 64-bit link, all symbols are exported by default, so is not necessary to
make symbols visible. However, it has an additional side effect of identifying all exported symbols as necessary, so
that they will not be removed when using dead code elimination
Force load all member objects of the archive library
lib. If you do not use the linker only loads the needed archive members from lib. This option is useful for creat-
ing a shared library from an archive library (if the member objects are position-independent code), or when you need
to load archive member that define symbols needed by shared libraries.
You can specify more than one library on the command line with multiple option-library pairs; that is, each library
you specify must be preceded by the option.
Strip all unloadable data from the output file.
This option is typically used to strip debug information.
Instrument the code to collect profile information upon execution.
The profile data gathered during program execution can be used in conjunction with the option. 32-bit programs
linked with this option should use the startup file This option should not be used with the or options.
Search for or in dir before looking in default locations. More than one directory can be specified, but each must be preceded
by The option is effective only if it precedes the option on the command line.
Turn on linker optimizations.
Currently the optimizations include the elimination of unnecessary instructions from the code in the executable file
(32-bit only), and the removal of dead procedures.
is passed to the linker by the compilers when the compiler option is selected.
This option is incompatible with the option.
For more details on linker optimizations refer to the option or the manual.
Examine the data file produced by an instrumented program
(see the option) to perform profile based optimizations on the code. This option should not be used with the or
options.
Ignored for 64-bit links.
Generate an executable output file with file type or depending on whether or is specified. This is the default.
This option is incompatible with
Set the origin (in hexadecimal) for the text (i.e., code) segment.
When used with the option, if you change the offset after the initial incremental link, the linker performs an ini-
tial incremental link automatically.
In 32-bit mode, save the load data and relocation information
in temporary files instead of in memory during linking. This option reduces the virtual memory requirements of the
linker. If the environment variable is set, the temporary files are created in the specified directory, rather than
in
In 64-bit mode, this option is equivalent to the option.
Output a message giving information about the version of
being used.
Allow run-time dereferencing of null pointers.
See the discussions of and pointers in cc(1). (This is the complement of the option.)
Reorder debuggable functions.
Ordinarily does not reorder functions from files with debugging information, because reordering renders them non-
debuggable. This option overrides this and reorders the functions. Reordering is based on link order file produced
from by default. If you specify the option, the linker uses the specified link order file, instead of for reorder-
ing. This option is incompatible with
Save link order file generated by
during linking with option into user-specified file. This option is incompatible with the option.
Indicate to the linker to use the specified file for the linker file
instead of generating it using This option is incompatible with the option.
Instruct the linker to replace the function symbol with an alternate function
symbol in shared library and executable file links.
The option supports function symbol aliasing. Often user programs have functions that exactly match the functional-
ity of optimized library functions with a different name. These user-defined functions are usually called frequently
in the program. With the option, you can make significant gains in performance by replacing all references to a
user-defined function with references to a tuned library function during link time, thus optimizing these functions
with just a relink.
Both functions must define the same number and type of parameters, and return a value of the same type. If they do
not match, the results are unpredictable, and the linker does not generate a warning message.
Example:
In the example, the linker replaces all references to the function symbol func_sym1 with references to func_sym2.
The func_sym2 symbol should be an normal unaliased symbol. It cannot appear on the left-hand side of "=" on another
option.
You can specify more than one function symbol alias on the command line with multiple option-symbol pairs, that is,
each symbol pair you specify must be preceded by the option.
Allows multiple symbol definitions.
By default, multiple symbol definitions that occur between relocatable objects will result in a fatal error condi-
tion. This option suppresses the error condition and allows the first symbol definition to be taken.
Specify a colon-separated list of directories
(embedded path) to be searched at program run-time to locate shared libraries needed by the executable output file
that were specified with either the or option.
An argument consisting of a single colon indicates that should build the list using all the directories specified by
the option and the environment variable (see the option).
For 32-bit links, if multiple options appear on the link line, the FIRST one specified is recorded. Also, a double
colon is interpreted as location in which libraries are found at link time.
For 64-bit links, the LAST of multiple options is recorded in the output file by default. Use to change this default
behavior. A double colon does not have special meaning (i.e., treated as NULL entry).
This option is ignored for 32-bit links.
This option turns on compatibility mode in the linker -- 64-bit links mimic behavior of 32-bit links).
Copy objdebug space.
Used together with the
option, this option specifies that file should be used as the profile database file. The default value is See the
discussion of the environment variable for more information. This option is incompatible with the option.
When building a shared library or program,
mark the symbol for export to the dynamic loader. Only symbols explicitly marked are exported. When building a
shared library, calls to symbols that are not exported are resolved internally.
This option is similar to the
option in that it exports a symbol. However, unlike the option, does not alter the visibility of any other symbol in
the file.
In a 32-bit link or mode 64-bit link, it has the effect of exporting the specified symbol without hiding any of the
symbols exported by default. In a 64 link, all symbols are exported by default, so is not necessary to make a symbol
visible. However, it has the additional side effect of identifying the symbol as necessary, so that it will not be
removed when using dead code elimination Of course, still retains its export behavior if an option such as is also
given.
Instructs the linker to run the fastbind tool
on the executable it has produced. The executable should be linked with shared libraries. For more details refer to
fastbind(1), the option, or the manual. This option is incompatible with the option.
Pass the option to the fastbind tool. For more details refer to fastbind(1), the option, or the manual. This option is
incompatible with the option.
Enables the shared library filter mechanism, which allows you
divide a large library into a "filter" and several "implementation" libraries for more efficient organization of
shared libraries. shared_library_path specifies the location of the filter library. See the for more information.
Specify the terminator (finalizer) functions to be invoked in
forward order, the order the functions appear left to right on the command line. The terminator functions are called
in reverse of the depth-first order of initializers.
Use this option while building a shared library, an incomplete executable, or fully bound executable. Functions
specified with this option should take no arguments and return nothing (void functions). Terminators are invoked
only if calls They are not called if calls
Do not use with the option. (The linker ignores the option.)
You can specify more than one terminator function on the command line with multiple option-symbol pairs, that is,
each function you specify must be preceded by the option.
For more details on the terminator function, use the option or see the
Enable the global symbol table hash mechanism,
used to look up values of symbol import/export entries. The and related options provide performance enhancements
through use of global symbol table which improves searching for exported symbols. See dld.sl(5) and the for more
information.
Request a particular hash array size using the global symbol
table hash mechanism. The default value is 1103. The value can be overridden at runtime by setting the environment
variable to the value prime number. You can set the value using size file.
When building a shared library, record
internal_name as the name of the library. When the library is used to link another executable file (program or
shared library), this internal_name is recorded in the library list of the resulting output file instead of the file
system pathname of the input shared library.
That is, if is not used, the shared library does not have an internal name and when an executable is built with the
shared library, the linker records the library name that it looks at.
If internal_name is a fully-qualified pathname, it is recorded in the library list of any executable file it is sub-
sequently linked against. internal_name is a relative pathname or no directory component was specified, inter-
nal_name is to the file system directory component of the input shared library in the library list of any executable
file it is subsequently linked against.
If more than one +h option is seen on the link line, the first one is used and a warning message is emitted.
Starts the help window utility
which comes with some HP compilers. (You must be running the X window system and your environment variable must be
set to the name of your workstation or X terminal.) For more information, refer to the manual. See manuals(5) for
ordering information.
Specify the initializer functions to be invoked in reverse order, the order
the functions appear right to left on the command line. Initializers are called in depth-first order. For example,
when a shared library is loaded, the initializers in all its dependent libraries are called first.
Use this option while building a shared library, an incomplete executable, or fully bound executable. Functions
specified with this option should take no arguments and return nothing (void functions). Terminators are invoked
only if calls They are not called if calls
Do not use with the option. (The linker ignores the option.)
You can specify more than one initializer function on the command line with multiple option-symbol pairs, that is,
each function you specify must be preceded by the option.
For more details on the initializer function, use the option or see the
enables the feature to use
for reading the contents of shared libraries during linking. This is the default behavior. Linking is usually much
faster when input shared libraries are mmapped, as compared to buffered reading from disk.
disables the mmap feature and tells the linker not to mmap text segments of input shared libraries. The linker uses
buffered disk i/o to access information from the text segments of input shared libraries.
NOTE: Use only in cases where the link fails because of mmap failures due to lack of memory, as it can significantly
increase the link time due to disk I/O.
Change the path to use the argument as the "interpreter" program instead of the
Direct the linker to only create an executable if there were
no errors encountered during the link. If there were errors found (system errors or unresolved references), the out-
put file will be removed.
Enables shared library segment merging feature.
See description of shared library segment merging in the This enables all the data segments of the shared libraries
loaded at program startup to be merged. This increases run-time performance by allowing the kernel to use larger
size page table entries.
Enables the feature to use
for writing the output data. This is the default behavior. Linker enabled with is much faster.
Causes the linker to load all object modules before searching
any archive or shared libraries. Then it searches the archive and shared libraries specified on the command line in
left to right order. Repeats the left to right search of the libraries on the command line until there are no more
unsatisfied symbols, or the last search added no new definitions. This option is useful if two libraries are speci-
fied that have symbol dependencies on each other.
Do not copy objdebug space.
Use this option (with object files on the link line) to suppress the default behavior of copying LINKMAP space to the
executable file.
Override the compiler option, and copy all debug information to the executable file.
When used with leaves debug information in the object files instead of copying it to the executable file at link
time, resulting in shorter link times and smaller executables. The compile-time default, copies the debug informa-
tion to the executable file.
When you specify when compiling, the compiler places symbolic debugging information into the object files. By
default, the linker calls which compacts this debug information and copies it to the executable file. When was used
at compile time, the linker leaves the debug information in the object files. To debug the executable file, the HP
WDB debugger must have access to the object files. If you move the object files, use HP WDB's command to tell it
where the object files are. The option reduces link time and the size of the executable file by avoiding this copy-
ing of debug information.
The compile-time default is If the linker detects any object files that were compiled with it leaves the debug infor-
mation in those files. Any object files not compiled with have their debug information copied into the executable
file. You can leave debug information in some object files and not in others.
When archive members are not compiled with (and they contain debug information, that is, they were compiled with the
debug information from the archive members is copied into the by default. The linker does not copy debug information
from shared libraries into the regardless of whether they are compiled with or
Use the option when linking to explicitly tell the linker to copy all debug information to the executable file, even
from files compiled with
Disables the shared library segment merging feature.
This is the default.
Disables the feature and uses the normal buffering method to write into the output file. Do not use unless in cases like the sys-
tem has very low memory and the linker fails because of this.
Ignore debug information from non-objdebug objects or
archives and proceed in mode. This option can be passed from the C or C++ compiler command line as If you are debug-
ging only files compiled with the option, can improve link time by instructing the linker to bypass the processing of
debug information from files compiled with With the option, the linker suppresses the call to
(Use only before the
option or the name of a shared library.) Cause the linker to add before the shared library name in the shared
library list. At runtime, the dynamic loader determine the current directory of the parent module (shared library or
executable) and replaces for that directory name.
Example:
While the option is available, the recommended way to specify is in the embedded path with the option, for example,
For more details on use the option or see the
Request a particular virtual memory page size that should be used for data.
Sizes of and are supported. A size of allows the kernel to choose what page size should be used. A size of will
result in using the largest page size available. The actual page size may vary if the requested size cannot be ful-
filled.
Used together with the
option, this option specifies that name should be used to name the dataset corresponding to this program when writing
profile data into the database file. The default look-up name used is the name of the program as obtained from at
runtime.
Used together with the option, this option specifies that name should be used as the look-up name (dataset name as
mentioned above) in the profile database file. The default is the basename of the output file (specified by the
option).
This option is incompatible with the option.
Request a particular virtual memory page size that
should be used for instructions. See the option for additional information.
Controls the size of profiling counters.
The acceptable value for this variable is 16 or 32. A warning is issued if the value specified is other than 16 or
32. The default value of the counter is 16, which is used if a valid value is not specified. Value at linktime can
be overridden by using environment variable. See the description in gprof(1) for more details.
This option turns on the linkage table protection mode.
When this option is used, the linker aligns the linkage table within page boundaries so that no other data resides in
the same page. At runtime, the pages containing the linkage table are marked READ_ONLY.
This option turns on immediate binding. For more information about immediate binding, see binding under option
The options incompatible with this option are: and
Indicates that at run-time, the shared library loader
can use the environment variable and (64-bit only) to locate shared libraries needed by the executable output file
that were specified with either the or option. The environment variables should be set to a colon-separated list of
directories. If both and are used, their relative order on the command line indicates which path list will be
searched first (see the option).
This option is ignored for 32-bit links.
Turns on standard mode, which is the default in 64-bit mode. The options turned on with this option is: Options
turned off or ignored when this option is specified are: and
This option is accepted but ignored by the 64-bit
Show more detail for any warnings about compatibility issues. By default, only a terse message is printed. See the
section below for further details.
This option is accepted but ignored by the 64-bit
Enable [disable] printing warnings about compatibility issues between systems. This includes any functionality which
may change in future releases. The default is See the section below for further details.
Enable [disable] printing a list of unsatisfied
symbols used by shared libraries. The default behavior in shared library build is and the default in executable
build is Some unsatisfied symbols reported by the linker are not required at run time because the modules which ref-
erence the symbols are not used.
Specify how the environment for floating-point
operations should be initialized at program start-up. By default, modes are specified by the IEEE floating-point
standard: all traps disabled, gradual underflow, and rounding to nearest.
The option supports the following modes (upper case flag enables; lower case flag disables):
Trap on invalid floating-point operations
Trap on divide by zero
Trap on floating-point overflow
Trap on floating-point underflow
Trap on floating-point operations that produce inexact results.
Enable sudden underflow (flush to zero) of denormalized values.
Enable rounding upward (toward +Infinity).
Enable rounding downward (toward -Infinity).
Enable rounding toward zero (truncate, chop).
Enable rounding to nearest (the default).
NOTE: Enabling sudden underflow is an undefined operation on PA-RISC 1.0-based systems, but it is defined
on all subsequent versions of PA-RISC. Selecting this flag enables sudden underflow only if it is avail-
able on the processor being used at run-time.
More than one mode can be specified with a comma separated list. For example:
specifies sudden underflow, trapping on overflow and invalid, and rounding toward zero. The commas and the space
between and the modes may be omitted. Thus, is equivalent to
To dynamically change these settings at run-time, see fesettrapenable(3M), fesetflushtozero(3M), and fesetround(3M).
Specify the name of the initializer function
when building a shared library. A shared library may have multiple initializers specified. Initializers are exe-
cuted in the order that they are specified. You can specify more than one initializer, but each must be preceded by
For more details on the initializer function, refer to the option or the manual.
Enable [disable] fast access to global data.
The linker rearranges the data to further reduce the number of instructions in the executable.
This optimization may reveal some subtle programming errors related to assumptions about data layout. This optimiza-
tion can occur at optimization levels 2, 3 and 4. The default is at optimization levels 2 and 3, and at optimization
level 4.
Using the option in the presence of debug information generates a warning message and can cause corruption of the
debug information. Avoid using with the option.
This option is accepted but ignored by the 64-bit
Enable [disable] the elimination of procedures and data that are not
referenced by the application. The default is
Procedure and data elimination can occur at any optimization level, i ncluding level 0. The elimination occurs on a
per section basis; the section is removed only if all procedures/data in the section are unreferenced. For more
details refer to the option or the manual. This option is incompatible with the option.
Note that compilers may set for higher optimization levels; refer to compiler documentation for detail.
Specify the name of the directory to use as the reuse repository for
the object code reuse feature. This directory holds the compiled object files for reuse. dir can be an absolute or
relative path to directory where you invoked the linker. The option shortens link time by not recompiling intermedi-
ate object code to object code when using or profile-based optimization.
Instructs the interprocedural optimizer driver to pass the first
n percent of the object files to the high level optimizer for interprocedural optimizations such as inlining.
Instructs the interprocedural optimizer driver to
pass the first k routines to the high level optimizer for interprocedural optimization where the size of k routines
are approaching but less than size.
Instructs the interprocedural optimizer driver to
compile the routines not included in the +O4 list to be compiled at +O3.
Meaningful only on PA-RISC 2.0 architecture, this option
sets the branch prediction bit in the output executable file's auxiliary header.
PA-RISC 32-Bit Options
This option specifies incremental loading.
Linking is arranged so that the resulting object can be read into an already executing program. The argument name
specifies a file whose symbol table provides the basis for defining additional symbols. Only newly linked material
is entered into the text and data portions of but the new symbol table reflects all symbols defined before and after
the incremental load.
Also, the option can be used in conjunction with which allows the newly linked segment to commence at the correspond-
ing address. The default starting address is the old value of
The option is incompatible with and
Also note that a program that dynamically loads code with cannot use shared libraries.
See the option or the manual for a description of this option.
Set the maximum parameter-checking level to
n. The default maximum is 3. See the language manuals for the meanings of the parameter-checking level.
Don't emit unwind tables.
Do not use this option if your compiler or tools require unwind tables.
Disable the linker feature that translates some calls to
to calls to
Generate an executable output file with file type
This option is incompatible with and This option causes the data to be placed immediately following the text, and
makes the text writable. Files of this type cannot be shared.
Generate an Initial Program Loader (IPL) auxiliary header
for the output file, instead of the default HP-UX auxiliary header.
Replace the recorded path for a shared
library in the In 32-bit mode, records the absolute path names of any shared libraries searched at link time in the
file. When the program begins execution, the dynamic loader attaches any shared libraries that were searched at link
time. Although you can use the and/or linker options to direct the dynamic loader to directories to search for the
shared libraries, the dynamic loader, as a last resort, searches for the shared libraries in its absolute, recorded
path in the
You can specify more than one shared library oldpath:newpath, but each must be preceded by the option.
Specify the use of
pathname as the code generator for compiling ISOMs to SOMs. See the discussion of profile based optimization in the
for more information.
Display verbose messages regarding procedures which have been
removed due to dead procedure elimination. The symbol name, input object file, and the size (in bytes) of the
deleted procedure are displayed. The total size (in bytes) of the deleted procedures is also displayed.
Exports all the symbols in the file
filename.
Request a particular number of buckets per entry using the global symbol
table hash mechanism. The default value is 3. The value can be overridden at runtime by setting the environment
variable to the value number. You can set the value using size file.
Disable SmartBind when binding a shared library.
With this option enabled, the linker places all symbols in the link into a single SmartBind module instead of placing
each file in its own module.
Enable the plabel caching mechanism.
Use this option with the option.
This option is only effective with C++. In C++ applications, the dynamic loader needs to repetitively access infor-
mation (import stub). In order to make this access faster, the dynamic loader uses the global symbol table structure
to also contain entries. This behavior is enabled when the flag is set in the dl_header structure (enabled or
PA-RISC 64-Bit Options
Preserve compiler generated relocation sections in output
file
Specify a mapfile that describes the output file memory map.
The user specified mapfile specifications are permitted with the option. But you should not modify the mapfile after
the initial incremental link. If the mapfile is modified after the initial link, an initial incremental link is per-
formed automatically.
Please refer to guide for more information. Also see
Specify the to optimize the hash table size (number of hash buckets). The valid values for bucketsizetype are:
Sets the number of hash buckets to half the number of dynamic symbols in the library.
Sets the number of hash buckets to the highest power of 2 that is less than the number of dynamic symbols in the
library.
Sets the number of hash buckets to the largest prime number that is less than the number of dynamic symbols in the
library. (This option is the default.)
When building a shared library, causes the linker to resolve all references
to the specified symbol to the symbol defined in the library. This option is similar to but operates on a per symbol
basis.
You can specify more than one symbol on the command line with multiple option-symbol pairs, that is, each symbol you
specify must be preceded by the option.
symbol can also be a regular expression that matches multiple symbol names. Regular expressions are described in
regexp(5).
Suppress all warnings.
Force storage allocation for hidden "common" symbols in
output. This is similar to the option, which allocates storage for all "common" symbols. If is specified in combi-
nation with the option, will take precedence.
(Kernel virtual environment support only.)
Allow generation of dynamic relocations in read-only sections such as and Normally the linker emits an error message
when a dynamic relocation is required in read-only sections. See for more information.
Does not flag errors if the resulting output file has unsatisfied symbols.
This is the default for relocatable links and shared library builds. Flags an error if the resulting output file has
unsatisfied symbols. This is the default for program files.
[Disable] Enable concatenation of search path specified
using
is the default.
Include any paths that are specified with in the embedded path, unless you specify the option. If you use only the
path list specified by is in the embedded path.
The option removes all library paths that were specified with the option from the embedded path. The linker searches
the library paths specified by the option at link time. At run time, the only library paths searched are those spec-
ified by the environment variables and library paths specified by the linker option, and finally the default library
paths.
loads all object files from archive
libraries. is the default -- loads only the required object files from archive libraries. The mode that is
selected, either explicitly or by default, remains on until it is changed.
This option is used to prevent all the symbols from being exported unless
explicitly exported with the
Specify incremental linking.
If the output file does not exist, or if it was created without the option, the linker performs an initial incremen-
tal link. The output file produced is suitable for subsequent incremental links. The incremental link option is
valid for both executable and shared library links.
NOTE: The HP WDB symbolic debugger only supports debugging of incrementally linked load modules that you create with
the compiler option enabled. (The HP DDE debugger does not support the option.)
To debug incrementally linked binaries, they should be compiled and linked with both and
If you specify one of the following incompatible option with the linker emits a warning message and ignores the
option.
o The option: create a relocatable object file.
o Strip options: and strip the output file. (The incremental linking requires the parts of the output load module
which are stripped out with these options.)
o Optimization options: file, name, and
The following options are compatible with the option with limitations:
o
Set the origin for the data and text segments. If you change the offset after the initial incremental link, the
linker performs an initial incremental link automatically.
o
provide a non-default mapfile. The user specified mapfile specifications are permitted with the option. But you
should not modify the mapfile after the initial incremental link. If the mapfile is modified after the initial
link, an initial incremental link is performed automatically.
Suppress incremental-linking related warnings.
By default, the linker issues all incremental-linking related warnings. This option is ignored if used without or
Control the amount of padding
percentage the incremental linker allocates, relative to sizes of object file structures being padded. By default
the linker allocates 25% of padding space. This option is ignored if used without or
Perform an initial incremental link, regardless of the output load
module.
In certain situations (for example, internal padding space is exhausted) the incremental linker is forced to perform
an initial incremental link. The option allows you to avoid such unexpected initial incremental links by periodi-
cally rebuilding the output file.
Used only when building a shared library.
This creates a shared library that can be used for interposition. When resolving references for an application with
direct binding information (see the dynamic loader searches interposer libraries first. If the symbol cannot be
resolved to any interposing libraries, the direct binding information is used.
Enable [disable] lazy loading of shared libraries.
Loading of shared libraries specified as is deferred until a reference is made to it during execution.
Dependent libraries of shared libraries will not be processed during link time, unless they are explicitly specified
on the link line.
Lazy loading can be disabled at runtime by setting the environment variable.
(Kernel virtual environment support only.)
Create linker-generated symbols even if building a shared library. The kernel with virtual environment support is
built with the option which by default does not create linker-generated symbols in shared libraries. See for more
information.
Pads the data segment with zeros, so that the data segment can be mapped
with a single call to at runtime. Normally, data segments require one call for file-backed storage and a second call
for blank static storage (bss). Use of this option increases your output file size.
This option tells the linker not to use the default memory map.
The user needs to supply a mapfile through the linker option.
Disables the default linker behavior of the
option to create the .dynhash section for executables or shared libraries. Use this option to eliminate generation
of pre-computed hash table information for a library or an executable that is rarely used with the global symbol ta-
ble lookup scheme or for which the overhead of storing pre-computed hash values is too high.
This option has no effect when used with the option.
Instructs the dynamic loader to not look at the
and environment variables at runtime. This is turned on if is specified. (The dynamic loader, however, uses the
environment variable with the option.) This is turned off by default or if is specified. See or Generally, this
option is used for secure programs (e.g.
Do not remove symbol when using dead code elimination This option can be used for hidden symbols as well as exported symbols.
You can specify more than one symbol on the command line with multiple option-symbol pairs, that is, each symbol you
specify must be preceded by the option.
Used with the option to allow procedures to be positioned independently. The default is to merge all procedures into a single sec-
tion.
When building a shared library with
causes the linker to exclude the specified symbol from symbol resolution.
You can specify more than one symbol on the command line with multiple option-symbol pairs, that is, each symbol you
specify must be preceded by the option.
symbol can also be a regular expression that matches multiple symbol names. Regular expressions are described in
regexp(5).
Pads the data segment to a multiple of
pagesize with zeros. This can improve page allocation, thus reduce TLB misses.
Pads the text segment to a multiple of
pagesize with zeros. This can improve page allocation, thus reduce TLB misses.
Generates a zero page of 4K bytes at the beginning of the data
segment. It also sets the default starting address of the data segment to 0x8000000000000000. This option improves
performance by reducing TLB misses by allowing the kernel to allocate bigger data pages.
Do not output the unwind table.
This creates smaller executable sizes. Use this option if you do not need the unwind table for debugging or C++
exception handling.
Request that the application be linked for profiling with CXperf.
Produces verbose output about the link operation.
type can have the following values:
Dump info about each object file loaded.
Dump info about the size of the heap used by a link.
Dump info about libraries searched.
Dump info about sections that have been rejected by the
option
Dump info about each input section added to the output file.
Dump info about global symbols referenced/defined from/in the input files.
Dumps all of the above info.
Same as
Defaults
Unless otherwise directed, names its output The option overrides this. Executable output files are of type The default state of is to
search shared libraries if available, archive libraries otherwise. The default bind behavior is
The default value of the option is
For 64-bit mode, is on by default.
Incremental linking with ld (64-bit Mode ONLY)
In the edit-compile-link-debug development cycle, link time is a significant component. The incremental linker (available through the and
can reduce the link time by taking advantage of the fact that you can reuse most of the previous version of the program and that the
unchanged object files do not need to be processed.
The incremental linker allows you to insert object code into an output file (executable or shared library) that you created earlier, with-
out relinking the unmodified object files. The time required to relink after the initial incremental link depends on the number of modules
you modify.
The linker performs the following different modes of linking:
o normal link: the default operation mode in which the linker links all modules.
o initial incremental link: the mode entered when you request an incremental link, but the output module created by the incremental linker
does not exist, or it exists but the incremental linker is unable to perform an incremental update.
o incremental link: the mode entered when you request an incremental link, an output module created by the incremental linker exists, and
the incremental linker does not require an initial incremental link.
Incremental links are usually much faster than regular links. On the initial link, the incremental linker requires about the same amount
of time that a normal link process requires, but subsequent incremental links can be much faster than a normal link. A change in one
object file in a moderate size link (tens of files, several megabytes total) normally is about 10 times faster than a regular link. The
incremental linker perform as many incremental links as allocated padding space and other constrains permit. The cost of the reduced link
time is an increase in the size of the executable or shared library.
The incremental linker allocates padding space for all components of the output file. Padding makes modules larger than those modules
linked by As object files increase in size during successive incremental links, the incremental linker can exhaust the available padding.
If this occurs, it displays a warning message and does a complete initial incremental link of the module.
When an object file changes, the incremental linker not only replaces the content of that file in the executable or shared library being
linked, but also adjusts references to all symbols defined in the object file and referenced by other objects. This is done by looking at
relocation records saved in the incrementally linked executable or shared library.
On the initial incremental link, the linker processes the input object files and libraries in the same way as the normal link. In addition
to the normal linking process, the incremental linker saves information about object files, global symbols, and relocations, and pads sec-
tions in the output file for expansion. On subsequent incremental links, the linker uses timestamps and file sizes to determine which
object files have changed, and updates those modules.
Under certain conditions, the incremental linker cannot perform incremental links. When this occurs, the incremental linker automatically
performs an initial incremental link to restore the process. In the following situations, the linker automatically performs an initial
incremental link of the output file:
o Changed linker command line, where the linker command line does not match the command line stored in the output file. (With the excep-
tions of the verbose and tracing options)
o Any of the padding spaces have been exhausted.
o Modules have been modified by the or options or tools (for example, strip(1)). The incremental linking requires the parts of the output
load module which are stripped out with these options.
o Incompatible incremental linker version, when you run a new version of the incremental linker on an executable created by an older ver-
sion.
o New working directory, where the incremental linker performs an initial incremental link if current directory changes.
o Archive or shared libraries are added/removed to/from the linker command line.
o Objects are added/removed to/from the linker command line.
See the Online Linker and Libraries User's Guide for more information.
The incremental linker searches an archive library if there are unsatisfied symbols. It extracts all archive members satisfying unsats and
processes them as new object files. If an archive library is modified, the linker replaces the modified archive library.
An object file extracted from an archive library in the previous link remains in the output load module even if all references to symbols
defined in the object file have been removed. The linker removes these object files when it performs the next initial incremental link.
In an initial incremental link, the linker scans shared library symbol tables and resolves unsats the same way it would in a regular link.
In incremental links, the linker does not process shared libraries and their symbol tables at all and does not report shared library
unsats. The dynamic loader detects them at run time. If any of the shared libraries on the command line was modified, the linker reverts
to an initial incremental link.
Performance of the incremental linker may suffer greatly if you change a high percentage of object files.
The incremental linker may not link small programs much faster, and the relative increase in size of the executable is greater than that
for larger programs.
Generally, the linker needs to scan through all shared libraries on a link line in order to determine all the unsats, even in incremental
links. This process may slow down incremental links. The incremental linker does not scan shared libraries and leaves detection of shared
library unsats to the dynamic loader.
Do not use the incremental linker to create final production modules. Because it reserves additional padding space, modules created by the
incremental linker are considerably larger than those created in regular links.
The HP WDB symbolic debugger only supports debugging of incrementally linked load modules that you create with the compiler option enabled.
(The HP DDE debugger does not support the option.
Any program that modifies an executable (for example, strip(1)), may affect the ability of to perform an incremental link. When this hap-
pens, the incremental linker issues a message and performs an initial incremental link.
Third-party tools that work on object files may have unexpected results on modules produced by the incremental linker.
Kernel Virtual Environment Support
For virtual environment support for the kernel, build your kernel with the following linker options (instead of the option):
By using these options, you create the kernel as a self-contained shared library with no exported symbols (with the and options). Because
the kernel contains references to linker-generated symbols such as and the option instructs the linker to create these symbols (which it
does not do for shared libraries by default). The kernel contains direct calls and relocations in read-only data space. Normally these
are applied at link time and are fixed up to link-time virtual addresses.
In the case of relocatable kernels, the linker needs to create dynamic relocations to fix up these references at run-time. The option
instructs the linker to allow dynamic relocations in read-only sections (Normally the linker issues an error message).
Security Restrictions
On a system that supports fine-grained privileges, if a process gains any privileges from the binary's extended attributes, dynamic path
lookup is disabled. Similarly, on a system that supports compartments, if a process changes compartment due to the binary's extended
attributes, the dynamic path lookup is disabled.
See setflexsec(1M) on how to set extended attributes on a binary. See privileges(5) and compartments(5) for more information about privi-
leges and compartments. Secure programs are programs that are commonly run by privileged users, such as or programs that run with elevated
privileges due to or protection. Special precautions should be taken when linking secure programs that use shared libraries. The default
linker behavior may be sufficient for 32-bit applications, but not for 64-bit applications.
Secure 64-bit programs should be linked with the option to disable the use of and for locating shared library dependencies. Secure 64-bit
programs should also link with to prevent the automatic construction of an embedded search path based on search directories specified with
options. Most directories searched at link time don't need to be searched at run time, and if these directories are specified as relative
paths, they expose the program to the same security risks as the use of and
Normal programs that depend on libraries that only exist in a directory specified in or (64-bit mode only) must be linked with to enable
searching and Programs that depend on or cannot be protected as setuid or setgid programs.
uses the dynamic path lookup (with and only if the following conditions are satisfied:
That is, if the or does not match its effective counterpart, does not check the directories specified in and which causes the runtime error
"".
EXTERNAL INFLUENCES
Environment Variables
The following environment variables affect the execution of
Specifies the path name of the HTML browser to display the when you use the option.
By default, when an instrumented executable (see the
option) writes the profile data, it creates a separate process which runs in the background; and the main process exits. If this
environment variable is set to "OFF", then a separate process is not created but the same process writes out the profile data. This
is useful if you get errors when removing or modifying the executable after it has been executed.
This environment variable is valid for 32-bit executables only. For instrumented shared libraries, profile data is always written
by the same process.
Serves the same purpose as
but for 64-bit executables.
An instrumented executable (see the
option) writes out the profile data to a database file named in the current directory. The name and location of this file can be
specified by setting to the desired path name. The profile data is stored in the database file under a look-up name that is the
same as the basename of the executable file specified at run-time. A single file can hold profile data
Arguments can be passed to the linker through the
environment variable as well as on the command line. The linker gets the value of and places its contents before any arguments on
the command line.
Specifies default directories
to search for library files. See the option.
Specifies, at runtime, directories
to search for library files. See the option, dld.sl(5), and the option for the manual for more information.
Specifies, at runtime, the path of the shared library to be
profiled (See HP-UX Linker and Libraries Online User's Guide for details.)
Specifies at runtime, the path of the profiler used to profile
shared libraries. The default value is for 32bit applications and for 64bit applications.
Specifies a directory
for temporary files.
The following internationalization variables affect the execution of
Determines the locale category for native language, local customs and coded character set in the absence of and other environment vari-
ables. If is not specified or is set to the empty string, a default of (see lang(5)) is used instead of
Determines the values for all locale categories and has precedence over
and other environment variables.
Determines the locale that should be used to affect the format
and contents of diagnostic messages written to standard error.
Determines the locale category for numeric formatting.
Determines the locale category for character handling functions.
Determines the location of message catalogs for the processing
of
If any internationalization variable contains an invalid setting, behaves as if all internationalization variables are set to See envi-
ron(5).
RETURN VALUES
returns the following values:
Successful completion.
The link is successful.
Failure.
An error has occurred.
EXAMPLES
Link part of a C program for later processing by (Note the suffix for the output object file; this is an HP-UX convention for indicating a
linkable object file):
On 32-bit, link a simple FORTRAN program for use with the symbolic debugger (see dde(1)). Output file name is since there is no option in
the command line.
To do this on 64-bit:
On 64-bit, link a shared bound program in standard mode. Note that is not specified because for shared links, it is no longer necessary.
On 64-bit, link a compatibility mode program. is included because this is an archive link.
Create a shared library:
Create a shared library with an internal name:
If you do not use the shared library does not have an internal name. The linker does not check whether is a symbolic link. It records the
library name that it looks at, if it does not have the internal name.
On 32-bit, link a program with but use the archive version of the C library. Specify the immediate binding mode together with the nonfatal
modifier and allow verbose diagnostics to be displayed:
To do this on 64-bit:
On 32-bit, link a Pascal program:
Note that in the above examples, can be replaced by
WARNINGS
recognizes several names as having special meanings. The symbol is reserved by the linker to refer to the first address beyond the end of
the program's address space. Similarly, the symbol refers to the first address beyond the initialized data, and the symbol refers to the
first address beyond the program text. The symbols and are also defined by the linker, but only if the program contains a reference to
these symbols and does not define them (see end(3C) for details). On 32-bit, the symbol is the total thread local storage size required by
the program or shared library.
On 64-bit, the linker defines a few more symbols. The symbol is the total thread local storage size. The symbol is the initial status of
the FPU status register. The symbol is the largest architecture revision level used by any compilation unit.
The linker treats a user definition of any of the symbols listed here as an error.
Through its options, the link editor gives users great flexibility. However, those who invoke the linker directly must assume some added
responsibilities. Input options should ensure the following properties for programs:
o When the link editor is called through cc(1), a start-up routine is linked with the user's program. This routine calls exit(2) after
execution of the main program. If users call directly, they must ensure that the program always calls rather than falling through the
end of the entry routine.
o When linking for use with the symbolic debugger dde, the user must ensure that the program contains a routine called Also, the user must
link in the file on 32-bit and on 64-bit as the last file named on the command line.
There is no guarantee that the linker will pick up files from archive libraries and include them in the final program in the same relative
order that they occur within the library.
The linker emits warnings wherever it detects any compatibility issues. Among other things, these issues include architectural ones, as
well as functionality that may change over time. Some of these include:
o Linking a PA 2.0 object file, which will not run on a PA 1.x system.
o Incremental loading with the option.
o Procedure call parameter and return type checking, including the option.
o Symbols with the same name but different types, such as CODE and DATA.
o Checking of unsatisfied symbols by the linker, which sometimes skips certain object files from an archived library. This warning
is only given if the option is also provided.
o Versioning of objects within a shared library.
These messages can be turned off with the option.
As noted in the Options section, certain options no longer exist in a 64-bit linker. They are:
o
o
o
o
o
o
o
o
AUTHOR
was developed by AT&T, the University of California, Berkeley, and HP.
FILES
32-bit system archive and shared libraries
64-bit system archive and shared libraries
32-bit development archive and shared libraries
64-bit development object files, archive and shared libraries
output file
32-bit dynamic loader
64-bit dynamic loader
for use with the 32-bit
debugger
for use with the 64-bit
debugger
32-bit run-time startup file
Identical to
64-bit run-time startup file
32-bit only.
Used with option links
32-bit run-time startup with profiling (see
prof(1))
32-bit millicode library automatically searched by
64-bit millicode library automatically searched by
run-time start-up with profiling (see
gprof(1))
32-bit run-time start-up with profiling (see
discussion of profile based optimization above.)
message catalog
temporary files
file containing profile data generated by running an
instrumented executable
program for creating the procedure link order from
a profile database file created by an instrumented executable; forked by the option
PA-RISC
code generator
SEE ALSO
Profiling and Debugging Tools
adb(1) absolute debugger
gprof(1) display call graph profile data
prof(1) display profile data
dde(1) C, C++, FORTRAN, and Pascal symbolic debugger
System Tools
aCC(1) invoke the HP-UX aC++ compiler
ar(1) create archived libraries
CC(1) invoke the HP-UX C++ compiler
cc(1) invoke the HP-UX C compiler
chatr(1) change program's internal attributes
exec(2) execute a file
f77(1) invoke the HP-UX FORTRAN 77 compiler
f90(1) invoke the HP-UX Fortran 90 compiler
fastbind(1) invoke the fastbind tool
nm(1) print name list of object file
pc(1) invoke the HP-UX Pascal compiler
strip(1) strip symbol and line number information from an object file
Miscellaneous
setflexsec(1M)
crt0(3) execution startup routine
end(3C) symbol of the last locations in program
a.out(4) assembler, compiler, and linker output
ar(4) archive format
compartments(5)
dld.sl(5) dynamic loader
privileges(5)
Texts and Tutorials
(See the option)
(See manuals(5) for ordering information)
STANDARDS CONFORMANCE
PA-RISC Systems Only ld_pa(1)