ld

Document Sample
ld Powered By Docstoc
					PorTS
 Portable Tool Suite
    Version 1.00



         ld




     14/11/2010
                                                                   PorTS ld (version 1.00)




Permission is granted to copy, distribute and/or modify this document under the terms
of the GNU Free Documentation License, Version 1.2 or any later version published
by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts,
and no Back-Cover Texts. A copy of the license is included in the section entitled
"GNU Free Documentation License".


Authors:
       Andrei Kapustin


Revision history


        Date                                    Comment

 14 Nov 2011          Initial draft.




                                                                              Page 2 of 36
                                                                                                                                   PorTS ld (version 1.00)



Table of Contents
1 OVERVIEW OF LINKER .................................................................................................................5
    1.1 VERSIONS OF LINKER ......................................................................................................................5
    1.2 INPUT AND OUTPUT FORMATS .........................................................................................................5

2 THE LINKING PROCESS.................................................................................................................7
    2.1 PROCESSING THE INPUT ..................................................................................................................7
        2.1.1 Treatment of static libraries...................................................................................................7
        2.1.2 Treatment of shared libraries.................................................................................................7
        2.1.3 Static vs. shared .....................................................................................................................8
        2.1.4 Import libraries......................................................................................................................9
        2.1.5 Resolving symbols..................................................................................................................9
             2.1.5.1 The read phase................................................................................................................................ 9
             2.1.5.2 The lookup phase ......................................................................................................................... 10
        2.1.6 Treatment of weak symbols ..................................................................................................10
        2.1.7 Compatibility issues .............................................................................................................10
    2.2 CONSTRUCTING THE OUTPUT ........................................................................................................11
        2.2.1 Output types .........................................................................................................................11
             2.2.1.1 Executables .................................................................................................................................. 11
             2.2.1.2 Shared libraries............................................................................................................................. 11
             2.2.1.3 Relocatable objects....................................................................................................................... 11
             2.2.1.4 Core images.................................................................................................................................. 12
        2.2.2 Segment and section binding................................................................................................12
        2.2.3 Handling of roaming sections ..............................................................................................13
        2.2.4 Handling of common symbols ..............................................................................................13
        2.2.5 Handling of entry points ......................................................................................................14

3 TARGET-SPECIFIC BEHAVIOR..................................................................................................15
    3.1 CEREON ........................................................................................................................................15
        3.1.1 Long branch veneers............................................................................................................15
        3.1.2 Veneer optimization .............................................................................................................17

4 USING LD..........................................................................................................................................21
    4.1 ENVIRONMENT VARIABLES ...........................................................................................................21
    4.2 LINKER OPTIONS ...........................................................................................................................21
        4.2.1 Option files...........................................................................................................................22
        4.2.2 Help options .........................................................................................................................22
        4.2.3 Diagnostics options..............................................................................................................22



                                                                                                                                                   Page 3 of 36
                                                                                                                   PorTS ld (version 1.00)


     4.2.4 Input options ........................................................................................................................24
     4.2.5 Output options......................................................................................................................25
     4.2.6 Target options ......................................................................................................................27
     4.2.7 Linking options.....................................................................................................................28

5 APPENDIX A: GNU FREE DOCUMENTATION LICENSE......................................................30




                                                                                                                                  Page 4 of 36
                                                                       PorTS ld (version 1.00)



1 Overview of linker
This document describes the linker available as part of the “development tools”
feature of the Portable Tool Suite (henceforth abbreviated as PorTS).
The linker combines object modules and libraries into executable images and shared
libraries. To do so, the linker may search additional libraries for definitions of missing
symbols, process link scripts, etc.
1.1 Versions of linker
The PorTS is a component-based tool suite that can come in several different
configurations, which differ by the set of facilities offered to the developers.
Currently, there are two such configurations:
   •   PorTS universal, which provides the complete set of development features,
       and
   •   CDS (Cereon Development Suite), which provides only those features that are
       required when developing software for Cereon targets.


Depending on the PorTS configuration, the developer tools use different names. The
following table summarizes these names for the linker:


                   Host OS
                                        Windows                  UNIX (Linux, etc.)
Configuration
PorTS universal                    ports-ld.exe                      ports-ld
CDS                                  cds-ld.exe                        cds-ld


In practice, the “.exe” file name extensions can be omitted when invoking the linker
tool on Windows, which makes the name of the linker platform-independent.
Furthermore, on both platforms it is possible to define either a symbolic link or a shell
script whose name is just ld and which, when executed, invokes the correct variant of
the linker.
1.2 Input and output formats
There exists a number of formats in which object files, libraries and executable files
can be represented.
When processing the input given to it, the linker will automatically determine the
format of various input files and treat them accordingly. This is achieved by analyzing
the actual content of each input file; the extensions given to the input files are
irrelevant.
When producing a linked output file, the linker will, by default, choose the format
appropriate for the selected target architecture & operating system. However, this can


                                                                                  Page 5 of 36
                                                      PorTS ld (version 1.00)


be overridden with a dedicated command line option.




                                                                 Page 6 of 36
                                                                          PorTS ld (version 1.00)



2 The linking process
The linker combines a number of object and library files, relocates their data and ties
up symbol references. Usually the last step in compiling a program or a shared library
is to run the linker.
2.1 Processing the input
The linker can handle several kinds of input files:
   •   Object files – an object file is a file that contains a single relocatable object
       module. Any number of object files can be given to the linker as inputs; all of
       them will be unconditionally included into the linked result.
   •   Linker script files – a linker script file is a text file containing a linker script,
       which instructs the linker on what it must do.
   •   Static libraries – a static library is a collection of object modules and/or linker
       scripts.
   •   Shared libraries – a shared library is a similar to an executable file in that all
       symbol references within it are resolved and it is ready to be loaded into the
       memory and executed. The difference is in that, unlike an executable file, the
       shared library will normally export some symbols; any program (or other
       shared libraries) that need to use these symbols can load the shared library at
       load- (or run-) time and refer to them as needed.
The linker makes sure that every input file is processed at most once, even if it
mentioned several times in the linker’s command line. Similarly, the linker makes
sure that every member of a static library, be it an object module or a linker script is
processed at most once.
2.1.1 Treatment of static libraries
There are two ways the linker can treat a static library depending on the way in which
that static library was supplied to the linker – full selection and on demand selection.
When a static library is supplied to the linker by being mentioned as one of the input
files (e.g. ports-ld a.o libobjs.a, where libobjs.a is the name of the
file containing the static library), all members of the library are forced to participate in
the linking; specifically, all linker scripts contained in the static library are effected,
then all object modules contained in the static library are selected for linking. This is
the full selection.
When, on the other hand, it is a library request (such as ports-ld a.o -lobjs)
that results in a static library being pulled in, the linker will only ever select those
object modules from that static library for linking that are needed to resolve undefined
external symbols. Any linker scripts that are included into a static library are effected
once when the first object module from that static library is pulled in. This is the on
demand selection.
2.1.2 Treatment of shared libraries
A shared library can be given to the linker either as an input file (e.g. ports-ld

                                                                                     Page 7 of 36
                                                                       PorTS ld (version 1.00)


a.o libutil.so) or via a library request (e.g. ports-ld a.o –lutil). In
either case, the symbols exported by the library are used to resolve whatever
undefined external references exist, but the shared library itself is not linked in –
instead, its name is merely noted in the linked executable file so that the
corresponding shared library can later be found at load-time.
2.1.3 Static vs. shared
When a library request (of the form –lname) is made, the linker will try to locate
both static and shared library with the specified name. The rules by which library
names are translated into file names depend upon the target OS for which the linking
is performed. For example:
   •   On UNIX platforms, the static library named <name> will be stored as a file
       lib<name>.a and the shared library in a file lib<name>.o.
   •   On Windows platforms, the static library named <name> will be stored as a
       file <name>.lib and the shared library in a file <name>.dll.
When the linker encounters only one variant of the required library compatible with
the target platform, it will use that variant. However, it can happen that both static and
dynamic variants of the same library exist. In this case, the following rules are used.
   1. If the command line option –Bstatic is specified, the linker requires that all
      library requests be satisfied by static libraries; any shared libraries that may
      have been used to resolve a library requests are ignored.
   2. If the command line option –Bdynamic is specified, the linker requires that
      all library requests be satisfied by shared libraries; any static libraries that may
      have been used to resolve a library requests are ignored.
   3. If the command line option –Bprefer-static is specified, the linker will
      resolve as many library requests as possible with static libraries; any
      remaining unresolved library requests will be resolved with shared libraries.
   4. If the command line option –Bprefer-dynamic is specified, the linker
      will resolve as many library requests as possible with shared libraries; any
      remaining unresolved library requests will be resolved with static libraries.
   5. If none of the above options is specified, the linker behaves in the same way as
      if –Bprefer-dynamic was in effect.


If you are linking with a number of libraries, and you want some of them to be static
and some shared:
   •   Specify shared libraries as input files explicitly; that will stop linker from ever
       finding their static versions.
   •   Specify static libraries as library requests to prevent them being pulled in
       completely.
   •   Use –Bstatic command line option to avoid accidentally linking against a


                                                                                  Page 8 of 36
                                                                          PorTS ld (version 1.00)


        shared variant of any static library.
2.1.4 Import libraries
For some target platforms (e.g. Windows) and object file formats (e.g. NGOFF) there
may exist a concept of an import library.
In all these cases, an import library is a bridge between a linked executable and some
shared library. It is, in itself, an object module or a static library (with a dedicated
filename extension, typically .ilb) that tells the linker that one or more global
symbols can be found in the specified shared library. The same effect can be achieved
with an appropriate linker script; indeed, it is entirely possible to have a linker script
with the .ilb filename extension that imitates an import library – although the linker
will correctly deduce that the file is a linker script and not an import library (by
analyzing its content), the net effect would be the same as if the linker script was, in
fact, an import library.
Since an import library, if used, invariably results in a need to link against a shared
library at load-time, linker scripts are treated in the same manner as shared libraries.
However, import libraries are never used to resolve library requests (e.g. the
command line library request option –lutil may be resolved by a static library
libutil.a or by a shared library libutil.so, but never by an import library
libutil.ilb, even if one exists).
2.1.5 Resolving symbols
The linker distinguishes between three symbol visibility levels:
    •   Local symbols are visibly only within an object module where they are
        defined. Because of that, they can be resolved locally for each object module.
    •   Module global symbols are visible across all object modules that are linked
        together to form an executable file or a shared library. However, once this has
        been done, module global symbols are not visible from other executable files
        or shared libraries. Therefore, module global symbols can be resolved during
        static linking but not during load-time or run-time dynamic linking.
    •   Global symbols are visible to the entire world. Therefore, they can be resolved
        during either static or dynamic linking.
The linker performs the static linking (and adds to the created executable or shared
library the information required for dynamic linking, if any).
All non-local symbols are resolved by name using the two-phase read/lookup
algorithm described below, repeated until no more symbols can be resolved (or,
normally, until all symbols are resolved).
2.1.5.1 The read phase
During the read phase, the linker scans all object modules that has not yet been
scanned. Initially, this list consists of all object files given to the linker as input and
all object module members of static libraries given to the linker as full selection
inputs.


                                                                                     Page 9 of 36
                                                                      PorTS ld (version 1.00)


While scanning each of these object modules, the linker records the names of all
global (and module global) symbols that are a) defined in each object module and b)
referred to by each object module.
At the end of the phase, the linker knows the names of all symbols that were referred
to but not defined in any of the scanned object modules. If there are no such symbols
(i.e. all referenced symbols have proper definitions), the algorithm ends. Otherwise,
the lookup phase follows.
2.1.5.2 The lookup phase
During the lookup phase, the linker examines all static libraries given to it in on
demand selection mode, and all shared libraries, in order in which they appear in the
command line. If a definition for one of the yet-undefined global symbols is found in
one of these libraries, that the linker attempts to find as many definitions for other
unresolved symbols as possible in that same library. That done, the linker marks the
found global symbols resolved, and:
   •   If the symbols were found in a shared library, records the fact that the shared
       library is a dependency of (i.e. required by) the executable or shared library
       that is being linked.
   •   If the symbols were found in a static library, the linker selects all library
       members which actually define these symbols and adds them to the list of yet-
       to-scan object modules.
Once the lookup phase has finished, the linker will restart the read phase, scanning the
newly pulled in object modules for other global symbol definitions and references.
However, if the lookup phase has failed to resolve any additional symbols, the read
phase is not restarted, as it repeated attempts to resolve any more symbols will not do
any good.
2.1.6 Treatment of weak symbols
Many object module formats allow tagging global symbols as “weak”. The linker will
use the following rules when processing such weak globals:
   •   No attempt is made to resolve any of the undefined weak symbols via the
       library search. If actual definitions for the required symbols are found, they are
       used; any unresolved weak globals are assigned the value of zero (0).
   •   Unlike “strong” (i.e. non-weak) global symbols, which permit only one
       definition across all linked object modules, many weak definitions of the same
       global symbol are permitted. If there is also a strong definition for the same
       symbol, it is used and all weak definitions are ignored; otherwise one of the
       weak definitions is selected arbitrarily and the other ones discarded.
2.1.7 Compatibility issues
The symbol resolution process described above will, if necessary, go over the same
library multiple times as long as doing so produces resolutions for more and more
undefined symbols. This behavior, while typical for some environments (e.g. virtually
all C/C++ development toolchains on MS Windows behave in the same way), would


                                                                               Page 10 of 36
                                                                      PorTS ld (version 1.00)


be unfamiliar to the user whose experience is mostly with the GNU GCC toolchain, as
the GNU linker will normally scan each library given to it only once and then never
return to it again.
The choice of the repeated-scan behavior over the scan-once behavior is deliberate, as
the latter makes the result of linking depend on the order in which libraries were
specified in the linker’s command line. If each global symbol is defined exactly once,
then the order of libraries should not matter, and the repeated scan will always
produce the same result as scan-once. If, on the other hand, there are several
definitions for some global symbols, the scan-once approach makes it too easy to
resolve symbols to wrong definitions due to possible errors in ordering the libraries.
Therefore, an ex-GNU developer shall remember that the PorTS linker always acts as
if all libraries were given to it as one group.
2.2 Constructing the output
Once all input object modules (and linker scripts) have been analyzed, only then does
the linker begin to construct the output.
2.2.1 Output types
The linker can produce several types of an output file:
   •   Executable
   •   Shared libraries
   •   Relocatable (partially linked) object
   •   Core image
2.2.1.1 Executables
When instructed to produce an executable file, the linker will process all offered input
object modules and perform the library search to resolve the undefined external
references, then constructing an executable module containing just enough
information for the target OS to load and start the program. At this point sections and
symbols are no longer relevant, so the linker would not emit any into the constructed
executable file (except dynamic symbols that must be resolved with shared libraries at
load-time).
2.2.1.2 Shared libraries
The linker will constructs a shared library in a manner similar to an executable file
with one difference – all global symbols defined by the shared library are retained in
its symbol table, as they would later be needed for linking other executables (and
shared libraries) that refer to these symbols.
2.2.1.3 Relocatable objects
When instructed to perform a partial link, the linker will merely combine all input
object modules into another relocatable object module, which can later be linked
again to produce an executable, a shared library, etc. Because the linker output is
designated for further linking, the linker will retain as much information as possible;


                                                                               Page 11 of 36
                                                                     PorTS ld (version 1.00)


that includes sections, symbols (even local symbols), etc.
2.2.1.4 Core images
The “core image” is a pure binary image that can be loaded at a specific address into
the target architecture’s memory and executed in there. The process of linking a core
image is similar to linking an executable; however, unlike executable file, the core
image generated by the linker would not contain any auxiliary information (i.e. there
will be no segments, no dynamic symbols requiring load-time linking, no dynamic
relocations, etc.).
2.2.2 Segment and section binding
Segments and sections defined in input object modules are bound by name. In
particular:
   •   All segments in all input object modules that have the same name are
       assembled into a single output segment with the same name.
   •   Similarly, all sections in all input object modules that have the same name are
       assembled into a single output sections with the same name.
   •   A segment without a name (the so-called anonymous segment) is never
       combined with other segments, even with other anonymous segments defined
       in the same object module.
   •   Similarly, a section without a name (the so-called anonymous section) is never
       combined with other sections, even with other anonymous sections defined in
       the same object module.
When several input segments (or several input sections) are bound together into one
output segment (or section), their properties (such as access permissions, alignment,
etc.) are combined insofar as possible as long as such combination does not introduce
conflicts. Specifically:
   •   The access permissions (read/write/execute) are joined; the output segment (or
       section) will have all access permissions enabled by any of the combined input
       segments (or sections).
   •   If any of the input segments (or sections) specify alignment requirements, the
       output segment (or section) will end up with the largest of them.
   •   If any of the input segments (or sections) specify size limit requirements, the
       output segment (or section) will end up with the smallest of them.
   •   If any of the input segments (or sections) specify numeric model, calling
       convention, etc., the output segment (or section) will end up having the same
       numeric model, calling convention, etc. However, of input segments (or
       sections) disagree on any of these properties, an error is reported.
Some object module formats allow binding sections to specific segments directly in
the object module (notably, NGOFF), or permit expressing such binding by the use of
special section attributes (ELF). A situation may then occur that several object
modules linked together define the same section (i.e. the section with the same name)


                                                                              Page 12 of 36
                                                                        PorTS ld (version 1.00)


with different segment binding. The following rules then apply:
   •   If a section is defined as bound (i.e. assigned to a particular segment) in one
       input object module, and as roaming (i.e. not assigned to any particular
       segment) in another input object module, it is considered bound to the segment
       in question.
   •   If a section is defined as bound to one segment in one input object module,
       and also as bound to a different segment in another input object module, an
       error is reported.
2.2.3 Handling of roaming sections
With a few exceptions, sections defined in input object modules would not normally
be bound to any specific segments (i.e. would be roaming sections). The linker
assembles such sections into artificially generated segments using the following rules:
   1. All roaming sections that have an explicit address are each assigned to a
      separate artificially created segment.
   2. All remaining roaming sections without write or execute permissions are
      collected into an RO (Read-Only) segment.
   3. All remaining roaming sections with write permission but without execute
      permission are collected into an RW (Read-Write) segment.
   4. All remaining roaming sections with execute permission but without write
      permission are collected into an RX (Read-eXecute) segment.
   5. All remaining roaming sections with both write and execute permissions are
      collected into an RWX (Read-Write-eXecute) segment.
Normally, the linker will assign “default” addresses to each of the segments created
by the steps 2..5 of the above (those segments created during step 1 do not need it, as
each of them is created for a specific section that has an explicit address assigned to it,
and inherits that address). The exact notion of what is a “default” address for a
specific segment depends on the target for which the linking is performed (for
example, when linking for Win32 target OS, default segments are laid out
sequentially starting at address 0x00400000). However, the “default” address for each
of these 4 segments can be explicitly overridden with a corresponding command line
option.
2.2.4 Handling of common symbols
When the linker sees a “common” symbol, it will record the fact and then try to match
that common symbol to any matching symbol definition. In that respect, common
symbols behave just like external symbol references. Note that, as local symbols are
not visible outside the object module where they are defined, a local common symbol
can never be resolved in that fashion. Note also that the linker will never try to
perform library search in order to resolve a nonlocal common symbol.
Once all the input object modules have been processed, the linker will create a new
artificial roaming section for each of the yet-unresolved common symbols, assigning
its size and alignment attributes as appropriate. All references to the common symbol


                                                                                 Page 13 of 36
                                                                      PorTS ld (version 1.00)


would then be redirected to the start of that section.
2.2.5 Handling of entry points
Many object file formats allow the program entry point to be specified in the
relocatable object modules (notably, the NGOFF format) or using special encoding
(e.g. ELF extended with an attributes section). In addition, the name of the entry point
symbol can also be specified from the command line.
When the linker decides on the entry point of the linked executable or shared library,
the following rules are used:
   •   If the name of the entry point symbol is specified from the linker’s command
       line, all entry point definitions occurring in the input object modules are
       ignored. The definition of the global symbol with the required name must
       exist; the linker will, if necessary, perform the library search to locate this
       symbol.
   •   If the name of the entry point symbol is not specified from the linker’s
       command line, the linker will use the entry point specification from an input
       object module, if there is one. If more than one input object module specifies
       the entry point, they must agree on what the entry point is; otherwise an error
       is reported.
   •   If none of the input object modules specify the entry point, the linked
       executable or shared library would not have an explicit point, in which case an
       implicit entry point named ___start (note the 3 leading underscores) is
       chosen (and, if necessary, a library search is performed to resolve it) unless a
       partial linking is performed; in the latter case the linked object would not have
       an entry point.




                                                                               Page 14 of 36
                                                                        PorTS ld (version 1.00)



3 Target-specific behavior
This section describes specifics of the linker behavior that depend upon the target
platform for which the linking is performed.
3.1 Cereon
The behavior described in this section only applies when linking for Cereon target
architecture.
3.1.1 Long branch veneers
The linker uses the technique known as “long branch veneers” to allow jump and
branch instructions to transfer control to any location within the 64-bit address space,
even though the actual Cereon instructions that implement jumps and branches have
limited range (specifically, a branch instruction can directly transfer control to any
other instruction within the [-215..215-1] instructions range, while jumps are limited to
a somewhat larger range of [-223..223-1] instructions).
Note that long branch veneers are not specific to the assembler language. Compilers
from high-level languages that target Cereon platforms will routinely assume the
linker’s ability to generate long branch veneers when generating code (specifically
procedure call/return instruction sequences).
In essence, when a jump or branch instruction with an implicit base (such as “j x” or
“beq.l $t0, $t1, x”) is translated and the jump target x is not within a range
that can be guaranteed to be reachable for the jump or branch in question (for
example, when x is an external symbol, or resides in a different section), the jump or
branch instruction is generated without a pre-calculated jump offset, but with an
appropriate relocation; it is also marked as being a jump or branch.
When linker later creates an image, it has two choices:
   •    If, in the generated image, the jump target x is reachable directly, the jump or
        branch instruction is relocated as necessary to do so (for example, the external
        jump target x may have ended up in the same section as the jump or branch
        instruction that uses it due to section joining). In this case, there is no overhead
        involved; the jump or branch instruction will transfer control directly to the
        jump target.
    • If, in the generated image, the jump target x cannot be safely reached by the
        jump or branch instruction, a long branch veneer is generated as described
        below.
A long branch veneer is a snippet of code that is:
    • Automatically generated by the linker if necessary,
    • Is guaranteed to be placed within a reachable range of the jump or branch
        instruction that uses it, and
    • Can transfer control anywhere within the 64-bit address space.
For example, consider an assembler language program that consists of one code
section and has, within that code section, a jump instruction that transfers control to
an external symbol:


                                                                                 Page 15 of 36
                                                                      PorTS ld (version 1.00)




            import      proc
.text:      section code
            jal         proc
            halt
.text:      end section


The actual implementation of the proc routine is, in this case, imported from a
dynamic-link library, which means that its address at runtime is more or less arbitrary.
After linking, the image will contain the following code:


            import      proc
.text:      section code
            jal         proc::veneer
            halt
            align       8
proc::address:
            long        proc
proc::veneer:
            lir         $ip, proc::address
.text:      end section


What happened here is the jump-and-link instruction being re-targeted to the veneer,
which loads a full 64-bit address of the jump target directly into $ip. When the proc
procedure performs return (by executing the “jr $ra” instruction), the control is
transferred back to the instruction following the jal, just as if jal was able to jump
to the proc entry point directly.
Depending on the code alignment, each long branch veneer is either 12 or 16 bytes
long. Naturally, the linker will try to minimize the total number of veneers it generates
so as to keep the code size to a minimum. Note, however, that veneers can only be
inserted at section boundaries; therefore if you have a 512KB section with a
conditional branch to an external label right in the middle, there will be no way for
linker to generate a veneer, as both section boundaries are far beyond the reach of a
conditional branch instruction.
Note also that the apparent loading of a jump target address from a code (i.e.
executable but not readable as data) section is no threat, as the Cereon lir instruction
has been specifically designed for this purpose – among other things, it requires

                                                                               Page 16 of 36
                                                                    PorTS ld (version 1.00)


“execute”, not “read”, memory access permission for the loading to succeed. If the
instruction “li.l $ip, -12[$ip]” was used instead, the example above would
not work, as loading the data from an execute-only section by “li.l” would have
caused a DACCESS (data access denied) exception instead.
3.1.2 Veneer optimization
The linker will also perform two more optimizations to further reduce the veneer size
– veneer pairing and veneer chaining.
Veneer pairing comes in handy when several consecutive veneers must be generated,
as in:


           import      proc1
           import      proc2
.text:     section code
           jal         proc1
           jal         proc2
           halt
.text:     end section


Normally, the linked image would contain the following code:


           import      proc1
           import      proc2
.text:     section code
           jal         proc1::veneer
           jal         proc2::veneer
           halt
           align       8
proc1::address:
           long        proc
proc1::veneer:
           lir         $ip, proc1::address
           align       8
proc2::address:
           long        proc

                                                                             Page 17 of 36
                                                                    PorTS ld (version 1.00)


proc2::veneer:
           lir         $ip, proc2::address
.text:     end section


Note that the second alignment directive “align 8” would introduce 4 bytes of
padding between veneers, as each veneer is 12 bytes long yet must be aligned on a 8-
byte boundary. With veneer pairing, the 2nd veneer of each pair is reversed in order,
giving:


           import      proc1
           import      proc2
.text:     section code
           jal         proc1::veneer
           jal         proc2::veneer
           halt
           align       8
proc1::address:
           long        proc
proc1::veneer:
           lir         $ip, proc1::address
proc2::veneer:
           lir         $ip, proc2::address
proc2::address:
           long        proc
.text:     end section


Now the 4 padding bytes between veneers are gone, as proc2::address is
guaranteed to be 8-byte-aligned.
The veneer chaining comes in handy when several veneers must be generated for
jump targets that are at a fixed offset of each other. Consider:


           extern      proc1
           extern      proc2
.text:     section code


                                                                             Page 18 of 36
                                                                PorTS ld (version 1.00)


            jal         proc1
            jal         proc2
            halt
.text:      end section


Now, suppose that the linker determines that both proc1 and proc2 are out of jump
range, but also that proc2’s address is exactly 200 bytes larger that proc1’s
address. While the direct approach is possible, as in:


            import      proc1
            import      proc2
.text:      section code
            jal         proc1::veneer
            jal         proc2::veneer
            halt
            align       8
proc1::address:
            long        proc
proc1::veneer:
            lir         $ip, proc1::address
proc2::veneer:
            lir         $ip, proc2::address
proc2::address:
            long        proc
.text:      end section


the shorter alternative would also work:


            extern      proc1
            extern      proc2
.text:      section code
            jal         proc1::veneer
            jal         proc2::veneer


                                                                         Page 19 of 36
                                                                     PorTS ld (version 1.00)


            halt
            align       8
proc1::address:
            long        proc
proc1::veneer:
            lir         $ip, proc1::address
proc2::veneer:
            lir         $rv, proc1::address
            addi.l      $ip, $rv, 200
.text:      end section


The veneer code is now 20 bytes long instead of 24. The use of $rv as a temporary
register is safe, because $rv is not expected to keep its value across procedure calls
or be initialized when proc2 is called. Naturally, for this kind of optimization to be
applicable, the linker must be informed that one of the standard Cereon procedure
calling standards is in use.




                                                                              Page 20 of 36
                                                                       PorTS ld (version 1.00)



4 Using ld
The general syntax of the linker invocation is:
         <linker name> <options…> [--] <input files…>
where:
   •     <linker name> is the name of the linker executable. Unless a symbolic
         link (or a shell script) is used to invoke the linker, that name would depend on
         the PorTS configuration. For example, if you have the “PorTS universal”
         configuration installed (which allows all optional features of the PorTS
         development suite), the linker name would be ports-ld.
   •     <options> is the list of linker options. Use the -? option to print the
         options reference.
   •     The double-dash option --, if specified, tells the linker that all subsequent
         command line arguments are input file names, even if they look like options.
   •     <input files…> is the list of files for the linker to process.
4.1 Environment variables
The linker (and the tools it invokes internally) makes use of several environment
variables. The exact names of the used environment variables depends on the PorTS
configuration as follows:


                                 Role      The list of directories where ld
             Configuration                        looks for libraries
             PorTS universal            PORTS_100_LD_LIBRARY_PATH
             CDS                          CDS_100_LD_LIBRARY_PATH


The fact that both PorTS configuration name and PorTS version number appear in the
environment variable name allows several different configurations and/or versions of
PorTS to be installed on the same machine without interfering with each other, as
each will have its own set of environment variables, pointing to its own set of
libraries.
4.2 Linker options
The linker uses the GNU/Linux command line style. This means that:
   •     All options are case-sensitive. File names are case-sensitive of the host OS
         supports it (e.g. UNIX) or case-insensitive if it does not (e.g. Windows).
   •     Options may have short (one character form) (e.g. –g) or long form (e.g. –-
         debug).


                                                                                Page 21 of 36
                                                                       PorTS ld (version 1.00)


   •   Short options without an argument can be bundled together (e.g. –vg is the
       same as –v –g).
   •   Argument for a short option can be bundled with an option or specified as an
       argument following the option (e.g. –lc++ and –l c++ are the same).
   •   Argument for a long option can be bundled with an option or specified as an
       argument following the option (e.g. –-format=bin and –-format bin
       are the same).
   •   Input file names and options can be freely intermixed in the command line,
       unless the double-dash option -- is encountered; any command line argument
       appearing after that is assumed to be an input file name even if it looks like an
       option.
4.2.1 Option files
If the command line option has the form @<file name>, then the content of the
option file <file name> is parsed as a list of command line options that replaces
the corresponding command line argument. Within an option file:
   •   Line breaks are treated as spaces.
   •   The backslash character ‘\’ causes the next character to be treated as part of
       an option even if it would otherwise be considered option separator.
   •   Other option files can be invoked using the same syntax @<sub-option
       file name>.
4.2.2 Help options
Options in this category cause the linker to print helpful information about itself.


-?, -h, --help
       Prints the short options reference for the linker.


-V, --version
       Prints the version and copyright information of the linker.


-v, --verbose
       While performing the archiving operations, print additional messages about
       their progress.
4.2.3 Diagnostics options
Options in this category control diagnostics issued by the linker.




                                                                                Page 22 of 36
                                                                  PorTS ld (version 1.00)


-WN, --warning-level=N
    Use warning level N (0 <= N <= 4) for this invocation of the linker. If the
    warning level is not explicitly requested, the default warning level 2 is used.
    The higher the warning level, the more detailed warnings are issued. At
    warning level 0 all warnings are suppressed. At warning level 4 all warnings
    are issued.


--diag-disable=W,...
    Disables specific warnings. Each W must be a numeric warning code. Several
    warnings can be disabled in one options, e.g. --diag-
    disable=1020,1121.


--diag-enable=W,...
    Enables specific warnings. Each W must be a numeric warning code. Several
    warnings can be enabled in one options, e.g. --diag-
    enable=1020,1121.


--diag-error=W,...
    Instructs the linker to treat specific warnings as errors. Each W must be a
    numeric warning code. Several warnings can be promoted to errors in one
    options, e.g. --diag-error=1020,1121.


--diag-warning=W,...
    Instructs the linker to treat specific warnings as warnings. Each W must be a
    numeric warning code. Several warnings can be demoted to errors in one
    options, e.g. --diag-error=1020,1121. This option is useful in
    conjunction with –-diag-tough, which promotes all warnings to errors by
    default.


--diag-tough
    Treats all warnings as errors by default (unless demoted by –-diag-
    warning).


--diag-output=F
    Specifies where the diagnostics are written.
    The default form --diag-output=- has the same effect as not specifying
    this option at all; all warning and error messages are written to the standard

                                                                           Page 23 of 36
                                                                      PorTS ld (version 1.00)


       error stream; the same effect is also achieved by --diag-
       output=stderr. To send errors and warnings to the standard output, use -
       -diag-output=stdout.
       If the diagnostic destination F ends with a path component separator (typically
       ‘/’, or ‘\’ on Windows) it is treated as the name of directory where the
       diagnostic file is created. The name of the diagnostics file is formed by
       replacing the extension of the linker output file (if any) with .err. So, for
       example, if the linker is invoked as ports-ld –-diag-output=err/
       -oa.out b.o c.o, then the invocation would create the file err/a.err
       containing all diagnostics.
       If the diagnostic destination F does not end with a path component separator, it
       is treated as the name of the diagnostic file where all errors and warnings are
       written. So, for example, if the linker is invoked as ports-ld –-diag-
       output=err.txt –oa.out b.o c.o, then the invocation would create
       one file err.txt containing all diagnostics.


--diag-encoding=E
       By default, the linker uses the default host character encoding for all error and
       warning messages. If this option is specified, it instructs the linker to use the
       character encoding with the specified name instead. Use –-diag-
       encoding=list to print the list of all supported encodings.
4.2.4 Input options
These options govern the treatment of input by the linker.


-LN, --library=N
       Instructs the linker to look for undefined external symbols in the library named
       N. The exact rules by which the library name is translated into the name of the
       file where the library is stored may vary depending on the target OS for which
       the linking is performed. For example, when linking a Linux executable, the
       option –Lncurses will refer to either a static library file libncurses.a
       or a shared library file libncurses.so (whichever one is found); when
       linking a Windows executable, however, the same option will refer to either a
       static library file ncurses.lib or a shared library file ncurses.dll
       (whichever one is found).


-LP, --libpath=P
       Instructs the linker to look for libraries in specified directory. The command
       line can contain any number of –L options if several include paths must be
       specified. A single –L option can also list several directories separated by
       default path separator used by the host OS (‘:’ on UNIX, ‘;’ on Windows);

                                                                               Page 24 of 36
                                                                          PorTS ld (version 1.00)


       therefore the two options -Lx –Ly can be abbreviated to –Lx:y (on UNIX)
       or –Lx;y (on Windows).
       The directories specified by this options are searched before the directories
       defined by an appropriate environment variable (e.g.
       PORTS_100_LD_LIBRARY_PATH if the linker is part of the PorTS
       universal configuration, etc.). This allows substituting user’s version of
       libraries for system versions.


--nostdlib
       If this option is specified, library directories specified by an appropriate
       environment variable (e.g. PORTS_100_LD_LIBRARY_PATH) are not
       searched. In this case, the user must explicitly specify locations where
       standard libraries can be found.
4.2.5 Output options
Options in this category control the output produced by the linker.


-oF, --output=F
       Instructs the linker to write the output to file or directory F.
       If F ends with a path component separator (‘/’ on UNIX, ‘\’ on Windows),
       then F denotes a directory (which is created if it does not yet exist). The output
       file is written into that directory; its name is deduced based on input file
       name(s) and/or target platform; for example, when linking an executable file
       for Linux OS, the default output file name is a.out.
       If F does not end with a path component separator, it names the output file
       itself.


--exec-encoding=E
       By default, the linker assumes that the application or shared library it produces
       will, during its execution, use the same character encoding as was the default
       encoding on the host where it was linked. Sometimes, that’s not the case (for
       example, when developing for a legacy platform such as IBM/360, which is
       EBCDIC-based, on either UNIX or Windows, both of which use ASCII –
       based encodings).
       If this option is specified, it instructs the linker to assume the specified
       encoding for the execution environment. Use –-exec-encoding=list to
       print the list of all supported encodings.


--link-map


                                                                                   Page 25 of 36
                                                                     PorTS ld (version 1.00)


    Instructs the linker to write the link map to the default map file. The name of
    the default map file is obtained from the name of the output file (whether the
    latter is explicit or implicit) by replacing its extension with .map.


--map-file=F
    Instructs the linker to write the link map to the file or directory F.
    If F ends with a path component separator (‘/’ on UNIX, ‘\’ on Windows),
    then F denotes a directory (which is created if it does not yet exist). The output
    file is written into that directory; its name is obtained from the name of the
    output file (whether the latter is explicit or implicit) by replacing its extension
    with .map.
    If F does not end with a path component separator, it names the map file itself.


--map-encoding=E
    By default, the linker writes the link map using the default host character
    encoding. If this option is specified, it instructs the linker to use the specified
    encoding for the link map. Use –-map-encoding=list to print the list of
    all supported encodings.


-FN, --format=N
    Requests the linker to write the linked output file in the specified format. Use
    –Flist to list supported output formats. If this option is not specified, output
    file is written using the default format for the selected target platform.


-g, --debug
    Instructs the linker to generate debugging information.


--shared
    Instructs the linker to produce a shared library instead of an executable
    module.


--core
    Instructs the linker to produce a core image instead of an executable module.


--partial
    Instructs the linker to produce a partial link. This links together all object


                                                                              Page 26 of 36
                                                                      PorTS ld (version 1.00)


       modules specified as an input, but produces a relocatable object module,
       suitable for further linking, as an output.
4.2.6 Target options
Options in this category define the target platform for which the program is linked and
where it will eventually run.


-TN, --target=N
       Instructs the linker to link for the specified architecture or CPU. Use -Tlist
       to list supported architectures and CPUs.
       If the option is specified, the target name N can name either an architecture
       (e.g. –Tcereon) or a specific CPU (e.g. –Tcereon-1P1B). In the former
       case, the default CPU for the requested architecture is used.
       If the option is not specified, the target architecture is derived from the object
       modules linked together; the first object module which defines a target CPU or
       architecture is used.


-YN, --os=N
       Instructs the linker to link for the specified OS. Use -Ylist to list supported
       target operating systems.
       If the option is not specified, the target OS is derived from the object modules
       linked together; the first object module which defines a target OS is used.


-MN, --model=N
       Instructs the linker to assume the specified numeric model for the linked
       executable file or shared library. Use -Mlist to list available models.
       If the option is not specified, the target model is derived from the object
       modules linked together; the first object module which defines a target model
       is used.


--wchar_t=N
       Instructs the linker to use the wide character type wchat_t of the specified
       size N, which could be 1, 2 or 4.
       Whether a specific wide character size is allowed depends on target OS. For
       example, compiling for Win32 enforces the 16-bit wide character type,
       whereas compiling for a freestanding environment allows you to select any
       wide character size you want.
       If the option is not specified, the wide character size is derived from the object
       modules linked together; the first object module which defines a wide

                                                                               Page 27 of 36
                                                                      PorTS ld (version 1.00)


       character size is used.


-BN, --byte-order=N
       Specifies the byte order that will be used by the CPU where the linked
       application or shared library has to run. Valid values are –BB (big-endian) and
       –BL (little-endian).
       Note that some architectures and/or CPUs only support a single byte order. For
       example, trying to link for an IA-32 CPU in a big-endian mode would be
       reported as an error.
       If the option is not specified, the byte order is derived from the object modules
       linked together; the first object module which defines a byte order is used.


-CN, --pcs=N
       Tells the linker that the specified calling convention is used for functions. Use
       -Clist to list available calling conventions.
       Note that the calling convention is dependent on the selected target
       architecture – the “standard” calling conventions for IA-32 and Cereon are
       very different, even though both have the same name.
       If the option is not specified, the calling convention is derived from the object
       modules linked together; the first object module which defines a calling
       convention is used.
4.2.7 Linking options
Options in this category control the linking process.


--ro-base=A
--rw-base=A
--rx-base=A
--rwx-base=A
       Instructs the linker to use the specified address for a roaming segment of the
       specified type instead of the default.
       All sections the linker sees in input object modules that are not explicitly
       assigned to a segment (the so-called roaming sections) are bundles together
       based on their access mode attributes. For example, all roaming read-only (i.e.
       not write or execute) sections would be assembled into a single read-only
       segment (the const segment). Similarly, all roaming read-write (i.e. not
       execute) sections would be assembled into a single read-write segment (the
       data segment). By default, the linker “knows” the default address for each
       such segment for each target platform. The above options allow overriding the


                                                                               Page 28 of 36
                                                                   PorTS ld (version 1.00)


    addresses of these roaming segments.
    In all of these options, A must be a linear memory address, written as a
    sequence of one or more hexadecimal digits. As a special case, two or more of
    the above options are allowed to specify the same address, in which case the
    corresponding roaming segments are merged into one segment.


-eN, --entry=N
    Instructs the linker to use the specified global symbol as an entry point of the
    linked application or shared object. If this option is specified, it overrides any
    entry point definition that may have appeared within any input object modules.




                                                                            Page 29 of 36
                                                                       PorTS ld (version 1.00)



5 Appendix A: GNU Free Documentation License
Version 1.2, November 2002


Copyright (C) 2000,2001,2002           Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA              02110-1301     USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.


0. PREAMBLE
The purpose of this License is to linker a manual, textbook, or other functional and
useful document "free" in the sense of freedom: to assure everyone the effective
freedom to copy and redistribute it, with or without modifying it, either commercially
or noncommercially. Secondarily, this License preserves for the author and publisher
a way to get credit for their work, while not being considered responsible for
modifications made by others.
This License is a kind of "copyleft", which means that derivative works of the
document must themselves be free in the same sense. It complements the GNU
General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software,
because free software needs free documentation: a free program should come with
manuals providing the same freedoms that the software does. But this License is not
limited to software manuals; it can be used for any textual work, regardless of subject
matter or whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that contains a
notice placed by the copyright holder saying it can be distributed under the terms of
this License. Such a notice grants a world-wide, royalty-free license, unlimited in
duration, to use that work under the conditions stated herein. The "Document", below,
refers to any such manual or work. Any member of the public is a licensee, and is
addressed as "you". You accept the license if you copy, modify or distribute the work
in a way requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the Document or
a portion of it, either copied verbatim, or with modifications and/or translated into
another language.
A "Secondary Section" is a named appendix or a front-matter section of the
Document that deals exclusively with the relationship of the publishers or authors of
the Document to the Document's overall subject (or to related matters) and contains
nothing that could fall directly within that overall subject. (Thus, if the Document is in
part a textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical connection with the

                                                                                Page 30 of 36
                                                                      PorTS ld (version 1.00)


subject or with related matters, or of legal, commercial, philosophical, ethical or
political position regarding them.
The "Invariant Sections" are certain Secondary Sections whose titles are designated,
as being those of Invariant Sections, in the notice that says that the Document is
released under this License. If a section does not fit the above definition of Secondary
then it is not allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant Sections then
there are none.
The "Cover Texts" are certain short passages of text that are listed, as Front-Cover
Texts or Back-Cover Texts, in the notice that says that the Document is released
under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover
Text may be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy, represented
in a format whose specification is available to the general public, that is suitable for
revising the document straightforwardly with generic text editors or (for images
composed of pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or for automatic
translation to a variety of formats suitable for input to text formatters. A copy made in
an otherwise Transparent file format whose markup, or absence of markup, has been
arranged to thwart or discourage subsequent modification by readers is not
Transparent. An image format is not Transparent if used for any substantial amount of
text. A copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain ASCII without
markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly
available DTD, and standard-conforming simple HTML, PostScript or PDF designed
for human modification. Examples of transparent image formats include PNG, XCF
and JPG. Opaque formats include proprietary formats that can be read and edited only
by proprietary word processors, SGML or XML for which the DTD and/or processing
tools are not generally available, and the machine-generated HTML, PostScript or
PDF produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself, plus such following
pages as are needed to hold, legibly, the material this License requires to appear in the
title page. For works in formats which do not have any title page as such, "Title Page"
means the text near the most prominent appearance of the work's title, preceding the
beginning of the body of the text.
A section "Entitled XYZ" means a named subunit of the Document whose title either
is precisely XYZ or contains XYZ in parentheses following text that translates XYZ
in another language. (Here XYZ stands for a specific section name mentioned below,
such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To
"Preserve the Title" of such a section when you modify the Document means that it
remains a section "Entitled XYZ" according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that
this License applies to the Document. These Warranty Disclaimers are considered to
be included by reference in this License, but only as regards disclaiming warranties:


                                                                               Page 31 of 36
                                                                       PorTS ld (version 1.00)


any other implication that these Warranty Disclaimers may have is void and has no
effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or
noncommercially, provided that this License, the copyright notices, and the license
notice saying this License applies to the Document are reproduced in all copies, and
that you add no other conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further copying of the copies
you linker or distribute. However, you may accept compensation in exchange for
copies. If you distribute a large enough number of copies you must also follow the
conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may
publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have printed covers)
of the Document, numbering more than 100, and the Document's license notice
requires Cover Texts, you must enclose the copies in covers that carry, clearly and
legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover
Texts on the back cover. Both covers must also clearly and legibly identify you as the
publisher of these copies. The front cover must present the full title with all words of
the title equally prominent and visible. You may add other material on the covers in
addition. Copying with changes limited to the covers, as long as they preserve the title
of the Document and satisfy these conditions, can be treated as verbatim copying in
other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put
the first ones listed (as many as fit reasonably) on the actual cover, and continue the
rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than
100, you must either include a machine-readable Transparent copy along with each
Opaque copy, or state in or with each Opaque copy a computer-network location from
which the general network-using public has access to download using public-standard
network protocols a complete Transparent copy of the Document, free of added
material. If you use the latter option, you must take reasonably prudent steps, when
you begin distribution of Opaque copies in quantity, to ensure that this Transparent
copy will remain thus accessible at the stated location until at least one year after the
last time you distribute an Opaque copy (directly or through your agents or retailers)
of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well
before redistributing any large number of copies, to give them a chance to provide
you with an updated version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document under the
conditions of sections 2 and 3 above, provided that you release the Modified Version

                                                                                Page 32 of 36
                                                                        PorTS ld (version 1.00)


under precisely this License, with the Modified Version filling the role of the
Document, thus licensing distribution and modification of the Modified Version to
whoever possesses a copy of it. In addition, you must do these things in the Modified
Version:
A. Use in the Title Page (and on the covers, if any) a title distinct from that of the
Document, and from those of previous versions (which should, if there were any, be
listed in the History section of the Document). You may use the same title as a
previous version if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities responsible for
authorship of the modifications in the Modified Version, together with at least five of
the principal authors of the Document (all of its principal authors, if it has fewer than
five), unless they release you from this requirement.
C. State on the Title page the name of the publisher of the Modified Version, as the
publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications adjacent to the other
copyright notices.
F. Include, immediately after the copyright notices, a license notice giving the public
permission to use the Modified Version under the terms of this License, in the form
shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections and required
Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title, and add to it an item
stating at least the title, year, new authors, and publisher of the Modified Version as
given on the Title Page. If there is no section Entitled "History" in the Document,
create one stating the title, year, authors, and publisher of the Document as given on
its Title Page, then add an item describing the Modified Version as stated in the
previous sentence.
J. Preserve the network location, if any, given in the Document for public access to a
Transparent copy of the Document, and likewise the network locations given in the
Document for previous versions it was based on. These may be placed in the
"History" section. You may omit a network location for a work that was published at
least four years before the Document itself, or if the original publisher of the version it
refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title
of the section, and preserve in the section all the substance and tone of each of the
contributor acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered in their text and in
their titles. Section numbers or the equivalent are not considered part of the section
titles.


                                                                                 Page 33 of 36
                                                                        PorTS ld (version 1.00)


M. Delete any section Entitled "Endorsements". Such a section may not be included
in the Modified Version.
N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in
title with any Invariant Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify
as Secondary Sections and contain no material copied from the Document, you may at
your option designate some or all of these sections as invariant. To do this, add their
titles to the list of Invariant Sections in the Modified Version's license notice. These
titles must be distinct from any other section titles.
You may add a section Entitled "Endorsements", provided it contains nothing but
endorsements of your Modified Version by various parties--for example, statements
of peer review or that the text has been approved by an organization as the
authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of
up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the
Modified Version. Only one passage of Front-Cover Text and one of Back-Cover
Text may be added by (or through arrangements made by) any one entity. If the
Document already includes a cover text for the same cover, previously added by you
or by arrangement made by the same entity you are acting on behalf of, you may not
add another; but you may replace the old one, on explicit permission from the
previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give
permission to use their names for publicity for or to assert or imply endorsement of
any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under this License,
under the terms defined in section 4 above for modified versions, provided that you
include in the combination all of the Invariant Sections of all of the original
documents, unmodified, and list them all as Invariant Sections of your combined work
in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple
identical Invariant Sections may be replaced with a single copy. If there are multiple
Invariant Sections with the same name but different contents, linker the title of each
such section unique by adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number. Linker the same
adjustment to the section titles in the list of Invariant Sections in the license notice of
the combined work.
In the combination, you must combine any sections Entitled "History" in the various
original documents, forming one section Entitled "History"; likewise combine any
sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You
must delete all sections Entitled "Endorsements."


                                                                                 Page 34 of 36
                                                                       PorTS ld (version 1.00)


6. COLLECTIONS OF DOCUMENTS
You may linker a collection consisting of the Document and other documents released
under this License, and replace the individual copies of this License in the various
documents with a single copy that is included in the collection, provided that you
follow the rules of this License for verbatim copying of each of the documents in all
other respects.
You may extract a single document from such a collection, and distribute it
individually under this License, provided you insert a copy of this License into the
extracted document, and follow this License in all other respects regarding verbatim
copying of that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent
documents or works, in or on a volume of a storage or distribution medium, is called
an "aggregate" if the copyright resulting from the compilation is not used to limit the
legal rights of the compilation's users beyond what the individual works permit. When
the Document is included in an aggregate, this License does not apply to the other
works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the
Document, then if the Document is less than one half of the entire aggregate, the
Document's Cover Texts may be placed on covers that bracket the Document within
the aggregate, or the electronic equivalent of covers if the Document is in electronic
form. Otherwise they must appear on printed covers that bracket the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may distribute translations of
the Document under the terms of section 4. Replacing Invariant Sections with
translations requires special permission from their copyright holders, but you may
include translations of some or all Invariant Sections in addition to the original
versions of these Invariant Sections. You may include a translation of this License,
and all the license notices in the Document, and any Warranty Disclaimers, provided
that you also include the original English version of this License and the original
versions of those notices and disclaimers. In case of a disagreement between the
translation and the original version of this License or a notice or disclaimer, the
original version will prevail.
If a section in the Document is Entitled "Acknowledgements", "Dedications", or
"History", the requirement (section 4) to Preserve its Title (section 1) will typically
require changing the actual title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document except as
expressly provided for under this License. Any other attempt to copy, modify,
sublicense or distribute the Document is void, and will automatically terminate your
rights under this License. However, parties who have received copies, or rights, from
you under this License will not have their licenses terminated so long as such parties
remain in full compliance.

                                                                                Page 35 of 36
                                                                       PorTS ld (version 1.00)


10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free
Documentation License from time to time. Such new versions will be similar in spirit
to the present version, but may differ in detail to address new problems or concerns.
See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the
Document specifies that a particular numbered version of this License "or any later
version" applies to it, you have the option of following the terms and conditions either
of that specified version or of any later version that has been published (not as a draft)
by the Free Software Foundation. If the Document does not specify a version number
of this License, you may choose any version ever published (not as a draft) by the
Free Software Foundation.




                                                                                Page 36 of 36

				
DOCUMENT INFO