HP eld User Manual

eld Manual

Abstract

This manual describes how programmers can use eld, the object file linker for TNS/E,
to create loadfiles for execution on HP Integrity NonStop™ NS-series servers.

Product Version

N.A.

Supported Release Version Updates (RVUs)

This publication supports J06.03 and all subsequent J-series RVUs and H06.01 and all
subsequent H-series RVUs, until otherwise indicated by its replacement publications.

Part Number Published

527255-009 February 2012

Document History

Part Number Product Version Published

527255-004 N.A. July 2005

527255-005 N.A. May 2010

527255-007 N.A. August 2010

527255-008 N.A. May 2011

527255-009 N.A. February 2012

Legal Notices

© Copyright 2012 Hewlett-Packard Development Company L.P.

Confidential computer software. Valid license from HP required for possession, use or copying.
Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software
Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under
vendor's standard commercial license.

The information contained herein is subject to change without notice. The only warranties for HP
products and services are set forth in the express warranty statements accompanying such products
and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be
liable for technical or editorial errors or omissions contained herein.

Export of the information contained in this publication may require authorization from the U.S.
Department of Commerce.

Microsoft, Windows, and Windows NT are U.S. registered trademarks of Microsoft Corporation.

Intel, Itanium, Pentium, and Celeron are trademarks or registered trademarks of Intel Corporation or its
subsidiaries in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

Motif, OSF/1, UNIX, X/Open, and the "X" device are registered trademarks and IT DialTone and The
Open Group are trademarks of The Open Group in the U.S. and other countries.

Open Software Foundation, OSF, the OSF logo, OSF/1, OSF/Motif, and Motif are trademarks of the
Open Software Foundation, Inc.

OSF MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THE OSF MATERIAL PROVIDED

HEREIN, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE.

OSF shall not be liable for errors contained herein or for incidental consequential damages in connection

with the furnishing, performance, or use of this material.

© 1990, 1991, 1992, 1993 Open Software Foundation, Inc. This documentation and the software to

which it relates are derived in part from materials supplied by the following:

© 1987, 1988, 1989 Carnegie-Mellon University. © 1989, 1990, 1991 Digital Equipment Corporation.

© 1985, 1988, 1989, 1990 Encore Computer Corporation. © 1988 Free Software Foundation, Inc.
© 1987, 1988, 1989, 1990, 1991 Hewlett-Packard Company. © 1985, 1987, 1988, 1989, 1990, 1991,
1992 International Business Machines Corporation. © 1988, 1989 Massachusetts Institute of
Technology. © 1988, 1989, 1990 Mentat Inc. © 1988 Microsoft Corporation. © 1987, 1988, 1989, 1990,
1991, 1992 SecureWare, Inc. © 1990, 1991 Siemens Nixdorf Informationssysteme AG. © 1986, 1989,
1996, 1997 Sun Microsystems, Inc. © 1989, 1990, 1991 Transarc Corporation.

This software and documentation are based in part on the Fourth Berkeley Software Distribution under

license from The Regents of the University of California. OSF acknowledges the following individuals
and institutions for their role in its development: Kenneth C.R.C. Arnold, Gregory S. Couch,
Conrad C. Huang, Ed James, Symmetric Computer Systems, Robert Elz. © 1980, 1981, 1982, 1983,
1985, 1986, 1987, 1988, 1989 Regents of the University of California.

Printed in the US

eld Manual

Glossary Index Tables

Legal Notices

What’s New in This Manual v

Manual Information v
New and Changed Information v

About This Manual ix

Notation Conventions xi

1. Introduction to eld

eld Overview 1-1

Example Command Line 1-2
eld Functionality 1-2

Linker Version Information 1-3
Native Object Files 1-3
The Linker Command Stream 1-5

Obey Files and the Use of Standard Input 1-7
Example of Use 1-9

2. eld Input and Output

Host Platforms 2-1

Target Platforms

Filenames and The File Identifier 2-2

Output Object Files

The Creation of Output Object Files 2-5

Creating Segments of the Output Loadfile

Using a DLL Registry

Input Object Files 2-12

Using Archives

2-2

2-4

2-16

2-6

2-8

3. Binding of References

Overview 3-1
Presetting Loadfiles
To Preset or Not to Preset, and Creation of the LIC 3-7

3-5

Hewlett-Packard Company—527255-009

i

Contents

Handling Unresolved References 3-8
Using User Libraries 3-10
Creating Import Libraries 3-11

Ignoring Optional Libraries 3-14
Merging Symbols Found in Input Linkfiles 3-16
Accepting Multiply-Defined Symbols 3-17

Using the -cross_dll_cleanup option 3-19
Specifying Which Symbols to Export, and Creating the Export Digest 3-20

Public Libraries and DLLs 3-22
The Public Library Registry 3-23

4. Other eld Processing

Creating an Import Library at the Same Time That a DLL is Created 3-12

Creating Import Libraries From Existing DLLs 3-12

Rules For Data Items 3-17

Rules for Procedures 3-18

Processing of Code and Data Sections 3-21

Concatenating Code and Data Sections Found in the Input Linkfiles 3-21

Finding and Reading The Public DLL Registry (ZREG) File 3-23

4. Other eld Processing

Adjusting Loadfiles: The -alf Option 4-1

Additional rules about -alf 4-3

The -set and -change Options 4-8

eld Functionality for 64-Bit 4-12

Checking the C++ Language Dialect 4-12

Renaming Symbols 4-13

Creating Linker-Defined Symbols

Updating Or Stripping DWARF Symbol Table Information

Modifying the Data Sections that Contain Stack Unwinding Information

Creating the MCB 4-15

Processing of Floating Point Versions and Data Models 4-16

Specification of the Main Entry Point

Specifying Runtime Search Path Information for DLLs

Merging Source RTDUs 4-19

4-14

4-14

4-15

4-17

4-18

5. Summary of Linker Options

6.
Output Listings and Error Handling

General Information 6-1
Error Messages 6-4

eld Manual—527255-009

ii

Contents

Glossary of Errors 6-126

A. TNS/E Native Object Files

The Object File Format A-1

Basic Properties of Object Files A-1
Types of TNS/E Object Files A-2
How to Distinguish the Different Types of Object Files A-3
Summary of the Contents of an Object File A-3

Code and Data Sections A-11

User Code A-12
User Data A-13
The MCB (Master Control Block) A-14
Predefined Symbols A-14

Relocation Tables A-16

How -alf Updates DWARF A-24
Finding Information About Procedures and Subprocedures in Linkfiles A-26

The DWARF Symbol Table A-26

A. TNS/E Native Object Files

Archives A-27
Tools That Work With Object Files A-29

Glossary

Index

Tables

Table 2-1. Parameters to the -instance_data Option 2-7
Table 4-1. The -set and -change Options 4-8
Table 5-1.
Table 6-1. Completion Codes - The Severity Levels of Messages 6-1
Table A-1. Types of TNS/E Object Files A-2
Table A-2.
Table A-3.

Table A-4.

Set Attributes 5-8

Contents of a Loadfile or Import Library A-5
Additional Predefined Symbols Optionally Created By The Linker In

Loadfiles A-15
Relocation Types A-18

eld Manual—527255-009

iii

Contents

eld Manual—527255-009

iv

What’s New in This Manual

Manual Information

eld Manual

Abstract

This manual describes how programmers can use eld, the object file linker for TNS/E,
to create loadfiles for execution on HP Integrity NonStop™ NS-series servers.

Product Version

N.A.

Supported Release Version Updates (RVUs)

This publication supports J06.03 and all subsequent J-series RVUs and H06.01 and all
subsequent H-series RVUs, until otherwise indicated by its replacement publications.

Part Number Published

527255-009 February 2012

Document History

Part Number Product Version Published

527255-004 N.A. July 2005

527255-005 N.A. May 2010

527255-007 N.A. August 2010

527255-008 N.A. May 2011

527255-009 N.A. February 2012

New and Changed Information

Changes to the H06.24/J06.13 manual:

In the section, The Steps in Looking for Archives and DLLs on page 2-17:

•

Updated the fourth and fifth step and also added a new content on page 2-17.

°

Updated information on 2-18.

°

In the section, Additional rules about -alf on page 4-3:

•

Updated the list on page 4-4.

°

In the table, The -set and -change Options on page 4-8:

•

Added a new entry on page 4-8.

°

eld Manual—527255-009

v

What’s New in This Manual

Updated the information on the attributes for -set and -change option on

°

pages 4-9 and 4-10.

Added eld Functionality for 64-Bit on page 4-12.

•

In the table, Set Attributes on page 5-8:

•

Added a new entry on page 5-8.

°

In the title, Output Listings and Error Handling on page 6-1:

•

Updated the message 1557 on page 6-95.

°

Added a new message 1510 on page 6-77.

°

Added a new message 1665 on page 6-124.

°

Added a new message 1666 on page 6-124.

°

Added a new message 1667 on page 6-125.

°

Added a new message 1668 on page 6-125.

°

Changes to the 527255-008 manual:

Added a new message 1669 on page 6-125.

°

Added a new message 1670 on page 6-125.

°

Added a new message 1672 on page 6-125.

°

Changes to the 527255-008 manual:

Added a new message 1132 on page 6-20.

•

Changes to the 527255-007 manual:

Added the following linker options:

•

-NS_extent_size extent-size on page 5-6

°

-NS_max_extents max_extents on page 5-7

°

-warn_common on page 5-12

°

Updated systype attribute information under Target Platforms on 2-2.

•

Added Using the -cross_dll_cleanup option on page 3-19.

•

Added information about -cross_dll_cleanup on page 5-2.

•

Added the following new messages:

•

1233 on page 6-39 to 1236 on page 6-39

°

1389 on page 6-69

°

1391 on page 6-69

°

Updated error message 1519 on page 6-79.

•

eld Manual—527255-009

vi

What’s New in This Manual

Added applicability note for data2protected parameter support on page 2-7 and

•

3-16.

Updated list of sections under Binding of References on page 3-1.

•

Changes to the 527255-005 Manual:

Updated information on how the linker searches for indirect DLLs on page 2-12

•

and 2-19.
Added consideration for -set libname on page 3-10.

•

Added consideration for -change libname on page 4-10.

•

Added the following error messages:

•

1229 to 1232 on page 6-38

•

1657, 1659, and 1660 on page 6-124

•

Changes to the 527255-005 Manual:

eld Manual—527255-009

vii

What’s New in This Manual

Changes to the 527255-005 Manual

eld Manual—527255-009

viii

About This Manual

This publication describes how programmers can use eld, the object file linker for
TNS/E, to create loadfiles for execution on H-series software NonStop servers.

Section 1, Introduction to eld consists of the following topics:

eld Overview - explains the general functionality of the product.

•

Native Object Files - introduces the different types of object files.

•

The Linker Command Stream - shows the conventions for entering tokens

•

(options, parameters and filenames) on the command line.

Example of Use - presents an example of using eld to link a main program and

•

a DLL .

Section 2, eld Input and Output consists of the following topics:

Host Platforms - where the linker may be used.

•

Target Platforms - where the output from the linker may be used.

•

Output Object Files - what forms (libraries, loadfiles and DLLs) that output may

•

take.

The Creation of Output Object Files - how you control that process.

•

Creating Segments of the Output Loadfile - how parts of a loadfile are created.

•

Using a DLL Registry - how you can manage DLL addressing.

•

Input Object Files - which files you can use as input.

•

Using Archives - how you can group multiple input or output files together.

•

Section 3, Binding of References consists of the following topics:

Overview - an overview of symbol resolution and code relocation.

•

Presetting Loadfiles - the process of resolving references to DLLs at linktime.

•

To Preset or Not to Preset, and Creation of the LIC - eld rules for presetting.

•

Handling Unresolved References - what happens if a symbol is not found in

•

any loadfile in the linker’s search list?

Using User Libraries - introduces the libname options.

•

Creating Import Libraries - three types are available.

•

Ignoring Optional Libraries - a command stream toggle is available.

•

eld Manual—527255-009

ix

About This Manual

Finding and Reading The Public DLL Registry (ZREG) File - three ways to find

•

it.

Section 4, Other eld Processing consists of the following topics:

Adjusting Loadfiles: The -alf Option - how to repeat the presetting of a loadfile

•

when DLLs change.

The -set and -change Options - how to set various options within the loadfile.

•

eld Functionality for 64-Bit - how the linker performs consistency checks.

•

Renaming Symbols - how the linker treats each input file.

•

Updating Or Stripping DWARF Symbol Table Information - from the input and

•

output object files.

Modifying the Data Sections that Contain Stack Unwinding Information - when

•

concatenating sections to create a new loadfile.

Creating the MCB - the Master Control Block contains key settings such as

•

product version numbers, valid file types, language dialects, and so on.

Processing of Floating Point Versions and Data Models - more consistency

•

checks.

Specification of the Main Entry Point - there are two ways to specify the main

•

entry point.

Specifying Runtime Search Path Information for DLLs - eld tells rld where to

•

find the DLLs.

Merging Source RTDUs - used with SQL/MP.

•

Section 5, Summary of Linker Options

option.

Section 6, Output Listings and Error Handling

General Information - when and how messages are created.

•

Error Messages - individual cause, effect and recovery information.

•

Glossary of Errors - a glossary of terms used in the error messages.

•

consists of a list and description of every linker

consists of the following topics:

Appendix A, TNS/E Native Object Files

The Object File Format - the types of object files and their content.

•

Code and Data Sections - the "ordinary" code and data sections that come

•

from application source code, possibly with additions by the compiler or linker.

consists of the following topics:

eld Manual—527255-009

x

About This Manual

Relocation Tables - when code is relocated, who resolves the address and

•

prepares relocation tables?

Finding Information About Procedures and Subprocedures in Linkfiles - an

•

introduction to the .procinfo and .procnames sections of linkfiles.

The DWARF Symbol Table - this table contains information used by debuggers

•

and the Cobol compiler.

Archives - contains an extension of material covered in a previous section of

•

this manual.

Tools That Work With Object Files - a quick look at which HP NonStop

•

operating system tools use object files.

Notation Conventions

The specific conventions for eld may be found in The Linker Command Stream on
page 1-5.

Notation Conventions

The conventions shown below are generic, applying to most manuals in the NonStop
Technical Library.

Hypertext Links

Blue underline is used to indicate a hypertext link within text. By clicking a passage of
text with a blue underline, you are taken to the location described. For example:

This requirement is described under Backup DAM Volumes and Physical Disk

Drives on page 3-2.

General Syntax Notation

This list summarizes the notation conventions for syntax presentation in most NonStop
manuals. Some of these conventions may not apply to this particular manual.

UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words. Type

these items exactly as shown. Items not enclosed in brackets are required. For
example:

MAXATTACH

lowercase italic letters. Lowercase italic letters indicate variable items that you supply.

Items not enclosed in brackets are required. For example:

file-name

computer type. Computer type letters within text indicate C and Open System Services

(OSS) keywords and reserved words. Type these items exactly as shown. Items not
enclosed in brackets are required. For example:

myfile.c

eld Manual—527255-009

xi

About This Manual

General Syntax Notation

italic computer type. Italic computer type letters within text indicate C and Open

System Services (OSS) variable items that you supply. Items not enclosed in brackets
are required. For example:

pathname

<filename>. TThis represents the name of a file. Filenames follow whatever rules apply to

the corresponding host platform when the linker needs to do something with the file.
For example, filenames are not case sensitive on Guardian or NT, but are case
sensitive on OSS. The linker keeps all filenames in the same form that they were
specified, unless otherwise stated in this document.

<symbol name> . This represents the name of a symbol as it appears within an object file.

It is case sensitive. There are rules that depend upon the source language for mapping
between the way the symbol appears in the source code and the way the symbol
appears within the object file. Each source language has its own rules for this.

<path> . This is the kind of string used in the -rld_L and -rld_first_L options.

<dllname>. This is the kind of string used in the -dllname option.

<location> . This is the kind of string used in the -L and -first_L options.

<number> . This indicates a 64-bit numerical value. It is interpreted as a hexadecimal

number if it begins with “0x”, “0X”, “%h”, or “%H”, in which case the rules given below
for a <hexadecimal number> apply. If it has none of these prefixes then it is interpreted
as a decimal number and the rest of the token must be a sequence of decimal digits.
The TNS/E linker does not accept octal numbers.

<hexadecimal number> . This indicates a 64-bit hexadecimal number, and may optionally

begin with “0x”, “0X”, “%h”, or “%H”. The letters “a” through “f” (representing the values
10 through 15) are not case sensitive. Periods are allowed in hexadecimal numbers to
subdivide the number for readability, using one of the following two methods. There
may be one period in the number, and then the period is assumed to divide the number
into two 32-bit portions. Or, there may be three periods, in which case the periods are
assumed to divide the number into four 16-bit portions.

<attribute> and <value>. These notations are explained under the description of the -set

option.

[ ] Brackets. Brackets enclose optional syntax items. For example:

TERM [\system-name.]$terminal-name
INT[ERRUPTS]

A group of items enclosed in brackets is a list from which you can choose one item or
none. The items in the list can be arranged either vertically, with aligned brackets on

eld Manual—527255-009

xii

About This Manual

General Syntax Notation

each side of the list, or horizontally, enclosed in a pair of brackets and separated by
vertical lines. For example:

FC [ num ]
[ -num ]
[ text ]

K [ X | D ] address

{ } Braces. A group of items enclosed in braces is a list from which you are required to

choose one item. The items in the list can be arranged either vertically, with aligned
braces on each side of the list, or horizontally, enclosed in a pair of braces and
separated by vertical lines. For example:

LISTOPENS PROCESS { $appl-mgr-name }
{ $process-name }

ALLOWSU { ON | OFF }

| Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in

brackets or braces. For example:

INSPECT { OFF | ON | SAVEABEND }

… Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you

can repeat the enclosed sequence of syntax items any number of times. For example:

M address [ , new-value ]…
[ - ] {0|1|2|3|4|5|6|7|8|9}…

An ellipsis immediately following a single syntax item indicates that you can repeat that
syntax item any number of times. For example:

"s-char…"

Punctuation. Parentheses, commas, semicolons, and other symbols not previously

described must be typed as shown. For example:

error := NEXTFILENAME ( file-name ) ;
LISTOPENS SU $process-name.#su-name

Quotation marks around a symbol such as a bracket or brace indicate the symbol is a
required character that you must type as shown. For example:

"[" repetition-constant-list "]"

Item Spacing. Spaces shown between items are required unless one of the items is a

punctuation symbol such as a parenthesis or a comma. For example:

CALL STEPMOM ( process-id ) ;

If there is no space between two items, spaces are not permitted. In this example, no
spaces are permitted between the period and any other items:

$process-name.#su-name

eld Manual—527255-009

xiii

About This Manual

Notation for Messages

Line Spacing. If the syntax of a command is too long to fit on a single line, each

continuation line is indented three spaces and is separated from the preceding line by
a blank line. This spacing distinguishes items in a continuation line from items in a
vertical list of selections. For example:

ALTER [ / OUT file-spec / ] LINE
[ , attribute-spec ]…

!i and !o. In procedure calls, the !i notation follows an input parameter (one that passes data

to the called procedure); the !o notation follows an output parameter (one that returns
data to the calling program). For example:

CALL CHECKRESIZESEGMENT ( segment-id !i
, error ) ; !o

!i,o. In procedure calls, the !i,o notation follows an input/output parameter (one that both

passes data to the called procedure and returns data to the calling program). For
example:

error := COMPRESSEDIT ( filenum ) ; !i,o

!i:i. In procedure calls, the !i:i notation follows an input string parameter that has a

corresponding parameter specifying the length of the string in bytes. For example:

error := FILENAME_COMPARE_ ( filename1:length !i:i
, filename2:length ) ; !i:i

!o:i. In procedure calls, the !o:i notation follows an output buffer parameter that has a

corresponding input parameter specifying the maximum length of the output buffer in
bytes. For example:

error := FILE_GETINFO_ ( filenum !i
, [ filename:maxlen ] ) ; !o:i

Notation for Messages

This list summarizes the notation conventions for the presentation of displayed
messages in this manual.

Bold Text. Bold text in an example indicates user input typed at the terminal. For example:

ENTER RUN CODE
?123
CODE RECEIVED: 123.00

The user must press the Return key after typing the input.

Nonitalic text. Nonitalic letters, numbers, and punctuation indicate text that is displayed or

returned exactly as shown. For example:

Backup Up.

eld Manual—527255-009

xiv

About This Manual

Change Bar Notation

lowercase italic letters. Lowercase italic letters indicate variable items whose values are

displayed or returned. For example:

p-register
process-name

[ ] Brackets. Brackets enclose items that are sometimes, but not always, displayed. For

example:

Event number = number [ Subject = first-subject-value ]

A group of items enclosed in brackets is a list of all possible items that can be
displayed, of which one or none might actually be displayed. The items in the list can
be arranged either vertically, with aligned brackets on each side of the list, or
horizontally, enclosed in a pair of brackets and separated by vertical lines. For
example:

proc-name trapped [ in SQL | in SQL file system ]

{ } Braces. A group of items enclosed in braces is a list of all possible items that can be

displayed, of which one is actually displayed. The items in the list can be arranged
either vertically, with aligned braces on each side of the list, or horizontally, enclosed in
a pair of braces and separated by vertical lines. For example:

obj-type obj-name state changed to state, caused by
{ Object | Operator | Service }

process-name State changed from old-objstate to objstate
{ Operator Request. }
{ Unknown. }

| Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in

brackets or braces. For example:

Transfer status: { OK | Failed }

% Percent Sign. A percent sign precedes a number that is not in decimal notation. The

% notation precedes an octal number. The %B notation precedes a binary number.
The %H notation precedes a hexadecimal number. For example:

%005400
%B101111
%H2F
P=%p-register E=%e-register

Change Bar Notation

Change bars are used to indicate substantive differences between this manual and its
preceding version. Change bars are vertical rules placed in the right margin of
changed portions of text, figures, tables, examples, and so on. Change bars highlight
new or revised information. For example:

eld Manual—527255-009

xv

About This Manual

The message types specified in the REPORT clause are different in the COBOL85
environment and the Common Run-Time Environment (CRE).

The CRE has many new message types and some new message type codes for
old message types. In the CRE, the message type SYSTEM includes all
messages except LOGICAL-CLOSE and LOGICAL-OPEN.

Change Bar Notation

eld Manual—527255-009

xvi

1 Introduction to eld

This section contains the following information topics:

eld Overview introduces the general functionality of the product.

Native Object Files introduces the different types of object files.

The Linker Command Stream shows the conventions for entering tokens (options,

parameters and filenames) on the command line.

Example of Use presents an example of using eld to link a main program and one

DLL.

eld Overview

The primary use of the linker eld, in the TNS/E development environments (Guardian,
OSS or PC), is to combine one or more TNS/E position-independent code (PIC) object
files into a new single loadfile.

eld manipulates both code and data, and then places all of the loadfile’s adjustable

references in tables outside the code to make them available to rld, the run-time
loader. This process, called linking, must be applied to linkfiles after they have been
compiled and before they can be loaded for execution.

Linkfiles are produced by a TNS/E compiler or assembler. The new loadfile created by

eld is either a program or a DLL. A loadfile contains certain information used to bind

references among loadfiles at load time. The linker may also look at other DLLs in
order to resolve references to them at link time (this is called “presetting”). A main
program, together with the DLLs that it needs directly or indirectly, is executed on the
HP NonStop operating system. A file type of 800 indicates that the code can only
execute on the TNS/E HP NonStop operating system platform.

The equivalent product for TNS/R PIC object files is known as ld and is documented
in the ld Manual.

rld is the run-time loader that may be used in either TNS/R or TNS/E environments.
rld is documented in the rld Manual.

As Guardian commands are case-insensitive you may use either upper (for example,

ELD) or lower-case (for example, eld) commands to invoke the linker. To comply with

UNIX conventions of lower-case usage, you may only use lowercase in the OSS
environment. This manual mostly uses lower-case versions of the linker names.

PIC native object files are generated by the native C, native C++, native COBOL, and
pTAL compilers. See the following manuals for information about these compilers:

C/C++ Programmer’s Guide

•

HP COBOL For NonStop Systems

•

pTAL Reference Manual.

•

eld Manual—527255-009

1-1

Introduction to eld

Example Command Line

The following is an example of a linker command line:

eld myobj1 myobj2 -o myprog -lib mydll

This command specifies linkfiles myobj1 and myobj2 as inputs to the linker, which is
named eld. The linker will combine them into the program named myprog, and will
bind references against a DLL found from mydll.

For a longer example of using eld, see the Example of Use on page 1-9.

eld Functionality

eld can also :

obtain its input linkfiles from archives.

•

combine existing linkfiles into a new linkfile with the -r option.

•

create an import library, including one that represents all the “implicit” libraries.

•

Example Command Line

bind references against user libraries and import libraries.

•

update an existing loadfile with the -alf, -change, and -strip options.

•

The linker does not have a programmatic interface other than starting it as a new
process, providing it the appropriate inputs, and looking at the outputs that it produces.

There are various ways of invoking the linker, such as directly from the command line,
indirectly from other command line tools such as the C compiler, or through graphical
user interfaces. You can run eld in these ways:

Manually, at a command prompt.

Automatically, when using these compilers:

Environment Compiler

Guardian CCOMP

CPPCOMP

ECOBOL

OSS c89

c99
ecobol

Windows NT*
Windows 2000*
Windows XP*

* By means of the Cross-Compiler CDs, ETK

This publication explains only how to run eld manually. For information on running eld
automatically, see:

All of the above and eptal

eld Manual—527255-009

1-2

Introduction to eld

C/C++ Programmer’s Guide

•

HP COBOL For NonStop Systems

•

eld runs in the following environments:

Guardian

•

OSS

•

Windows NT, Windows 2000, and Windows XP, using either the Cross-Compiler

•

CDs or the HP Enterprise Toolkit—NonStop Edition (ETK), which is based on
Microsoft Visual Studio .NET

Note. eld has the same capabilities and syntax in each environment, but each environment
has its own rules, for example, filename syntax.

Linker Version Information

eld writes information about its version number into the .tandem_info section of its

output object file.

Linker Version Information

eld also contains a VPROC procedure that is a standard feature of Tandem tools.
The PC version of eld contains version information that you can see by looking at the

"properties" of the eld.exe file.

Native Object Files

eld operates on TNS/E native object files. Native object files are in Executable and

Linking Format (ELF), a standard format used for object files, with some HP
extensions.

This manual presents only basic information about these files. For details on the
structure of native object files for TNS/E, see Appendix A, TNS/E Native Object Files

and the enoft Manual.

Native object files are either Linkfiles or Loadfiles, but not both.

Can Be Linked to Produce a Loadfile Can Be Executed

Linkfiles Yes No

Loadfiles No Yes

The native compilers create native object files called linkfiles from source code.

eld produces native object files called loadfiles from such linkfiles.

Native object files of TNS/E in the Guardian environment have a file code of 800.
Native object files of TNS/R in the Guardian environment have a file code of 700.

eld Manual—527255-009

1-3

Introduction to eld

There are four types of TNS/E object file:

Type of Object File Description

Linkfile Object files that are produced by a compiler or by the

Program This is the main program. There is one program in every

DLL This is a dynamic-link library. It is an object file that is not a

Import Library This is a file that contains just part of a DLL that is needed

Collectively, programs and DLLs are called loadfiles. Loadfiles and import libraries are
built by the linker.

Native Object Files

assembler that can be given as input to the linker. It is also
possible for the linker to produce a linkfile as output when
run with the -r option.

process.

program but can also be part of a process. A process can
contain any number of DLLs. DLLs are also used by the
linker when building other programs or DLLs.

at link time to build other DLLs or programs.

The main distinctions occur between linkfiles and loadfiles. There is little difference
between a program and a DLL as far as the file format is concerned, and an import
library is a subset of what is in a DLL.

A loadfile may refer by name to symbols that exist in other loadfiles in the same
process. Such references are resolved when the loadfiles are brought into memory by
the runtime loader (rld) or by the C/C++ runtime procedure named dlopen(). When
the loadfile was originally built by the linker it is also possible that the linker tried to
resolve such references. A loadfile whose references have been resolved by the linker
is said to be preset.

A process can also use one user library. A user library is a DLL. Nothing within a user
library distinguishes it from other DLLs, and a DLL that serves as the user library for
one program can also be used like any other DLL by other programs. The only
difference between the user library and other DLLs is in the way the program identifies
the user library that it uses. For a DLL to be used as a user library at runtime its
filename must be in the Guardian name space.

An import library can take the place of a DLL at link time. One use of import libraries is
to save space. Another use is for security, when it is necessary for the linker to read
the header information but it is not desirable for others to be able to see the code.
Import libraries are further categorized as complete or incomplete. The difference is
that an incomplete import library need not contain the correct addresses for symbols. A
complete import library can be used by the linker when presetting a loadfile. The linker
can use an incomplete import library to check for unresolved references, but not to
preset.

DLLs and import libraries can also be used at compile time by the COBOL compiler to
find out information about procedure call interfaces.

eld Manual—527255-009

1-4

Introduction to eld

Some DLLs are called public libraries because they are provided as part of the TNS/E
implementation and are found in a special way by the linker and runtime loader. A
public library has the same format as any other DLL, and can have an import library to
represent it.

Some of the public libraries are called implicit libraries because they are used at link
time and run time without explicit mention on the part of the user. There are several
implicit libraries, and there is a bit in a DLL that tells if it is an implicit library. A single
implicit library never has an import library to represent it to the linker. Rather, at link
time, when building a loadfile that is not an implicit library, a single import library
represents the entire set of implicit libraries. That is called the import library that
represents the implicit libraries, and it is always a complete import library.

For detailed information about PIC programs and developing DLLs, see the DLL
Programmer’s Guide for TNS/E Systems.

There is also an equivalent manual for TNS/R systems, the DLL Programmer’s Guide
for TNS/R Systems.

The Linker Command Stream

The Linker Command Stream

The following definitions of terms such as option, parameters and filenames is specific
only to eld. In other environments and products, similar concepts might go under
different names, for example OSS calls options “flags”.

The linker obtains tokens from the command line by using the argc and argv

functions of C. The way this works may be dependent on the C runtime
implementation, but the general idea is that tokens are separated by spaces. On the
PC it may be useful to include a space within a filename, and that can be done by
placing quotation marks around the name. The C runtime gives the name to the linker
without the surrounding quotation marks.

Certain options, such as the -obey option, cause the linker to obtain tokens from files,
and the linker mostly treats them the same as if they were on the command line. The
linker’s command line, plus the other tokens it obtains in such ways from files, are
collectively called the linker’s command stream.

Tokens are categorized as options, parameters, or filenames. An option always starts
with a hyphen. A filename or parameter never starts with a hyphen. Each option
requires a certain number of parameters to immediately follow it.
the linker cannot parse the command stream into a sequence of options and/or
filenames, where each option is followed by the required number of parameters.

eld reports an error if

Names of options and parameters must be spelled exactly as given in this manual.
Except for the options named -l and -L, options and keyword parameters are not
case sensitive.

Options may be placed into one of three categories:

eld Manual—527255-009

1-5

Introduction to eld

Repeatable options are options such that each occurrence of the option is

•

independent, such as providing another element of a list of information or making
the linker do a certain activity again.

Toggle options are options that modify the linker’s behavior for the remainder of the

•

command stream, or until toggled again.

One-time options are everything else.

•

Descriptions of repeatable options and toggle options within this manual explain the
significance of each occurrence of the option. If this manual does not explain why an
option might be given more than once in the command stream, it is a one-time option.
It is okay to specify a one-time option more than once if it doesn’t take any parameters,
and the repeated occurrences are ignored by the linker. It is similarly okay if the option
has a parameter and you specify the option more than once with the same parameter,
or with another parameter that is a “synonym” of it. eld reports an error if you specify a
one-time option more than once with non-synonymous parameters. With regard to one­time options that take string parameters, “synonymous” means exactly the same,
including the same case of all the characters, even in situations (e.g., filenames on
Guardian) where the case wouldn’t be significant. Except, because the parameter to ­set libname is converted to upper case by the linker anyway, this particular check
is not case sensitive. On the other hand, when there is a numerical parameter,
“synonymous” means that the value comes out the same, regardless of how it is
written.

The Linker Command Stream

With regard to the -set option, each combination of the -set option with one of its
attributes is treated as a single one-time option as mentioned in the previous
paragraph. In other words, there are no restrictions on how many times the -set
option can be given with different attributes. If -set is specified more than once with
the same attribute, and a value is required, that is okay if a synonymous value is given
each time, otherwise eld reports an error.

With regard to the -b option, this is really treated as two different options. There is a
one-time -b option, whose possible parameter values are globalized, localized,

semi_globalized, and symbolic, where symbolic is a synonym for
semi_globalized. And there is also a toggle -b option, where the possible

parameter values are dllsonly, dynamic, and static.

Throughout this manual, rules are given for which combinations of options are legal.
Even if not stated explicitly,
mutually exclusive from their descriptions.

Whenever the name of an option is a single letter and the option has a single
parameter it is permissible to omit the space between the option name and the
parameter, combining them into a single token. This would be ambiguous for an option
that takes a filename or symbol name as a parameter when the result is the name of
some other option, so the rule is that it is only permitted to leave out the space if this
does not cause such an ambiguity. For instance, if the output file is to be named b, it

can be specified as either -o b or -ob. However, if the output file is to be named bey
then it must be written -o bey because there is another option named -obey.

eld reports an error if you specify multiple options that are

eld Manual—527255-009

1-6

Introduction to eld

If no tokens are given to the linker in its command stream then the linker writes out
messages to the output listing to give a one-line summary of each of the available
options and does nothing else.

If some tokens are given, and based on these tokens the linker should create a new
object file from one or more linkfiles, but no linkfiles are brought into the link, eld
reports an error.

Obey Files and the Use of Standard Input

The -obey option lets the user put tokens into a file that is read by the linker. This file
is a text file, and must be either a file code 101, or a code 180 file. The parameter to
the -obey option is the name of the file, and anything that could be given on the linker
command line is permissible in that file. In simple cases the contents of the file are
treated the same as if they were on the command line, in the place of the -obey
option. White space in the obey file, including ends of lines, serves to separate tokens.

Within obey files, if a token begins with two consecutive hyphens, those hyphens and
the rest of the line are treated as a comment (ignored).

Obey Files and the Use of Standard Input

There is also a special rule with regard to (double) quotation marks within obey files.
The special rule only applies to a quotation mark that comes at the beginning of a
token, i.e., it is either the first character in the obey file or it follows white space. In this
case, if it is the last quotation mark on that line, eld reports an error. Otherwise, the
characters between it and the next quotation mark are considered to be a single token,
even if they include white space. The linker will then start looking for the next token
immediately after the second quotation mark. For example, if a line in an obey file
contains the following:

-o “abc -def”ghi

then the linker will consider this to contain three tokens, namely, “-o”, “abc -def”, and
“ghi”. Note that there is a space between the ‘c’ and the ‘-’, and that the name of the
output file created by the linker is “abc -def”. On some platforms this will work, and on
other platforms it won’t. Also note that no space is required between the second
quotation mark and the ‘g’. As another example, if a line in an obey file contains the
following:

-o abc“d e”f

then this contains two tokens after the -o, where the first token is abc”d and the
second one is e”f. The quotation marks do not fall under the special rule here, because
they are not at the beginnings of tokens. Thus, the space between the d and e serves
to separate tokens.

Note that the above examples show that it is possible to put a space in the middle of a
token, and that it is possible to put a quotation mark in the middle of a token, but it is
not possible to have both of these things in the same token.

There can be multiple -obey options on the command line, each being processed as
explained above. There can be -obey options within obey files, with no limit on the

eld Manual—527255-009

1-7

Introduction to eld

nesting. Recursive nesting is handled by the rule that an -obey option is ignored if its
parameter is identical to the parameter of an -obey option that is currently being
processed.

The -obey option has a synonym, -FL.
There is also an option named -stdin. This is the same as an -obey option except

that it doesn’t take a parameter and it signifies instead that the contents of the standard
input file are read at this point in the command stream. The linker reads from standard
input until it encounters end of file. If the runtime environment allows a process to read
standard input up to an end of file, and then read it some more until another end of file,
etc., then there can be more than one -stdin option in the linker command stream,
each one being processed the same way.

It is not an error if a -stdin option is found within the standard input file. It is simply
ignored, as a special case of the rule that recursive -obey options are ignored. The
linker doesn’t require input from the standard input file and the linker is often used
where standard input is interactive, with nothing being entered. Accordingly, it would be
a mistake for the linker to unconditionally read from standard input because then the
linker might wait forever, with the user not realizing that the linker was waiting for input.
That is why a special option such as -stdin is necessary, to say when input is
coming from standard input.

Obey Files and the Use of Standard Input

A special case is made, however, for the Guardian platform, where the linker
distinguishes an EDIT file from other types of input files. On the Guardian platform, if
the standard input file is an EDIT type file and nothing is specified on the command
line, the linker reads that EDIT type file to obtain its command stream.

Note that the -obey option is expanded like a macro, and can even be used to
provide the parameter to an option. For example, it is possible to say -rpath -obey
x, and then the initial token within the file named x would be used as the parameter
for the -rpath option. If the file named x contained additional contents after the
initial token, those additional tokens would be interpreted as additional filenames,
options, etc., following the -rpath option.

Similar considerations apply when an -obey option is a parameter to another -obey
option, for example, if you write -obey -obey x as pa

rt of the command stream. In

this case, the linker will first assume that x is the name of an obey file and expand the
contents of the file x in place of the -obey x. So, if the first token found within the file
x is, say, y (not starting with a hyphen), so that the expanded command stream now
looks like -obey y ..., the linker will assume that y is the name of an obey file and
expand the contents of the file y in place of the -obey y. Thus the command stream
will contain the contents of the file y , followed by the remaining contents of the file
named x after its initial token “y”.

eld Manual—527255-009

1-8

Introduction to eld

Example of Use

This section shows an example of using the eld linker. This example shows the use of

a main program, mainstrc, and a library called mystrngc. Both will be compiled using
ccomp, then linked using eld. mystrngc will be loaded as a DLL.

Display the Source Code

Here is the code for the main program, mainstrc

#include <stdio.h> nolist
#include <stdlib.h> nolist
#include <string.h> nolist
int StrRev (char *s, char *r); /* declaration of external procedure */

char s[100];
/***********************************************************

| main: given a list of strings, print out them reversed
| argv[1]...argv[argc-1] point to strings
|
| if no string passed, put out usage message and quit.
| for each string
| reverse it
| display it
|
\***********************************************************/
int main(int argc, char *argv[]) {
char **ppStr;
int strLeft;
int outcome;

if (argc < 2) /* no args passed */
{

printf("Usage: run rev <str1> [<str2>] ....\n \

\twhere <str> is a string to reverse\n \
\texample: run rev abc zyxw\n");
exit(1);
}

Example of Use

for (strLeft= argc-1, ppStr=argv+1;
strLeft;
ppStr++, strLeft-- ) {
strcpy(s, *ppStr);
outcome = StrRev( s, s );
(outcome == 0) ? printf( "Reverse(%s) = (%s)\n", *ppStr, s ) :
printf( "error in reversing the string\n");
} /* for */

printf("Hit enter to finish\n");
getchar( );
} /* of proc main */

Here is the source code for the library, mystrngc

#include <string.h> nolist
#include <stdlib.h> nolist

int StrRev (char *s, char *r ) {

eld Manual—527255-009

1-9

Introduction to eld

char *pBegin;
char *pEnd;
char c;
strcpy(r, s);
pBegin = r;
pEnd = r + strlen(r);
while (--pEnd > pBegin )
{
c = *pBegin;
*pBegin++ = *pEnd;
*pEnd = c;
}
return (0);

} /* StrRev */

Compile the Program and Library

The first step is to compile the programs using ccomp, the native mode TNS/E
compiler, on the HP NonStop operating system to create the two object files, mainstro
and mystro.

Example of Use

We are using a fully-qualified filename to get to the TNS/E compiler, ccomp. On your
system, the pathname showing the location of your development tools will be quite
different.

run $data01.toolsy02.ccomp /in mainstrc /mainstro; suppress
TNS/E C - T0549H01 - 30AUG2004 (Oct 25 2004 14:47:23)
(C)2004 Hewlett Packard Development Company, L.P.

0 remarks were issued during compilation.
0 warnings were issued during compilation.
0 errors were detected during compilation.
Object file: mainstro
Compiler statistics
phase CPU seconds elapsed time file name
CCOMP \SPEEDY.$DATA01.TOOLSY02.CCOMP
CCOMBE 0.2 00:00:07 \SPEEDY.$DATA01.TOOLSY02.CCOMBE
total 0.2 00:00:09
All processes executed in CPU 05 (NSR-Y)
Swap volume: \SPEEDY.$DATA01

eld Manual—527255-009

1-10

Introduction to eld

Here’s the creation of the object file called mystro.

run $data01.toolsy02.ccomp /in mystrngc /mystro;suppress
TNS/E C - T0549H01 - 30AUG2004 (Oct 25 2004 14:47:23)
(C)2004 Hewlett Packard Development Company, L.P.

0 remarks were issued during compilation.
0 warnings were issued during compilation.
0 errors were detected during compilation.
Object file: mystro
Compiler statistics
phase CPU seconds elapsed time file name
CCOMP \SPEEDY.$DATA01.TOOLSY02.CCOMP
CCOMBE 0.2 00:00:06 \SPEEDY.$DATA01.TOOLSY02.CCOMBE
total 0.2 00:00:06
All processes executed in CPU 04 (NSR-Y)

Example of Use

Swap volume: \SPEEDY.$DATA01

Build the DLL and the Program

First we build the DLL, then the main executable file called revstr. It has to be in that

order because the main executable could not refer to a DLL that did not yet exist. (If
the linker’s -allow_missing_libs option is specified, the main executable could be
linked befoe the DLL is linked.)

Note that the -lib option references the DLL called mystrdll. Note the -export_all

option. We could also individually reference the items to be exported, as follows:

-export StrRev

Note the -shared option sent to eld. This creates the DLL. The -dll option can be
used to do the same task, and is probably more descriptive of what we want to
achieve. Either option can be used.

eld Manual—527255-009

1-11

Introduction to eld

The following command input creates the DLL:

run $data01.toolsy02.eld mystro -o mystrdll -shared -export_all
eld - TNS/E Native Mode Linker - T0608H01 - 26OCT04
Copyright 2004 Hewlett-Packard Company

eld command line:
\speedy.$data01.toolsy02.eld mystro -o mystrdll -shared -export_all

**** INFORMATIONAL MESSAGE **** [1530]:
Using 'ImpImp' file: \speedy.$data01.toolsy02.zimpimp.

Output file: mystrdll (dll)
Output file timestamp: Nov 8 13:59:43 2004

No errors reported.

Example of Use

No warnings reported.
1 informational message reported.
Elapsed Time: 00:00:01

Now Build the Program

The next step is to create the loadfile (the whole program) by use of the linker.
ccplmain contains initialization code for the C and C++ run-time libraries. Your

version of that file will probably be located in $system.system.
ccplmain contains external references to errno and environ (which are defined in

ZCREDLL) and C_INT_INIT_COMPLETE_ , C_INT_INIT_START_ , and exit (which
are defined in ZCRTLDLL).

Note that each DLL must use an individual -lib option to be linked with eld. The
command syntax does not allow for a single -lib option followed by a list of DLLs, for
example: -lib zcredll, zcrtdll, mystrdll is not valid syntax.

eld Manual—527255-009

1-12

Introduction to eld

60> run $data01.toolsy02.eld $data01.toolsy02.ccplmain mainstro -lib
mystrdll&

60> & -lib zcredll -lib zcrtldll -o revstr -L $users.patrick -L
$data01.toolsy02 -verbose

eld - TNS/E Native Mode Linker - T0608H01 - 26OCT04
Copyright 2004 Hewlett-Packard Company

eld command line:
\speedy.$data01.toolsy02.eld $data01.toolsy02.ccplmain mainstro -lib
mystrdll -lib zcredll -lib zcrtldll -o revstr -L $users.patrick -L
$data01.toolsy02 -verbose

**** INFORMATIONAL MESSAGE **** [1019]:
Using DLL: $users.patrick.mystrdll.
**** INFORMATIONAL MESSAGE **** [1019]:

Example of Use

Using DLL: $data01.toolsy02.zcredll.
**** INFORMATIONAL MESSAGE **** [1019]:
Using DLL: $data01.toolsy02.zcrtldll.
**** INFORMATIONAL MESSAGE **** [1530]:
Using 'ImpImp' file: \speedy.$data01.toolsy02.zimpimp.

Output file: revstr (program file)
Output file timestamp: Nov 9 14:59:42 2004

No errors reported.
No warnings reported.
4 informational messages reported.
Elapsed Time: 00:00:02

Run The Program

RUN REVSTR XYZ
Reverse(XYZ) = (ZYX)
Hit enter to finish

eld Manual—527255-009

1-13

Introduction to eld

Example of Use

eld Manual—527255-009

1-14

2 eld Input and Output

This section contains the following information:

Host Platforms - where the linker may be used.

Target Platforms - where the output from the linker may be used.

Output Object Files - what forms (libraries, loadfiles and DLLs) that output may take.

The Creation of Output Object Files - how you control the process.

Creating Segments of the Output Loadfile - how parts of a loadfile are created.

Using a DLL Registry - how you can manage DLL addressing.

Input Object Files - which files you can use as input.

Using Archives - how you can group multiple linkfiles together for eld access.

Host Platforms

The TNS/E linker (eld) runs on several platforms, as follows.

The TNS/E linker runs on the TNS/E version of the HP NonStop operating system,

•

with both the Guardian and OSS personalities.

The TNS/E linker runs on TNS/R versions of the HP NonStop operating system.

•

This means you can link PIC object files into TNS/E loadfiles as part of your
development cycle on that platform - but you will not be able to execute those
loadfiles on TNS/R.

The TNS/E linker runs on appropriate versions of the Windows operating system

•

on PC’s.

The TNS/E linker’s features are the same for all host platforms unless otherwise
specified in this manual. Differences often relate to the different types of filenames and
file characteristics on different platforms.

The Guardian namespace also exists as a subset of the OSS file system, where a

Guardian file named $a.b.c corresponds to an OSS file named /G/a/b/c.

The Guardian namespace is a set of rules use for naming files in the Guardian
filesystem. A complete description of those rules may be found in the OSS filename

(5) reference page in the OSS System Calls Reference Manual.

Those rules include:

The Guardian namespace ignores lowercase, the OSS namespace uses

•

lowercase.

$ and \ are not recognized in the OSS namespace

•

If a filename contains a period in it, and a file of that name is to be created in a

•

Guardian subvolume, the period is deleted from the name.

eld Manual—527255-009

2-1

eld Input and Output

Text files in Guardian subdirectories of OSS are code 180 files, not edit files.

•

When the linker creates a text file in a Guardian subvolume of OSS it is a code
180 file. When the linker reads a text file in a Guardian subvolume of OSS,
code 180 files always work, and edit files do not necessarily work.

OSS has the concept of a “file mode” used to control UNIX file security and

•

access rules. This file mode does not apply to files in the Guardian
namespace.

Target Platforms

The loadfiles created by the TNS/E linker can only be loaded and run on the TNS/E
versions of the HP NonStop operating system. A process can be run in either one of
two environments “Guardian” and “OSS”, dependent on it’s process ID.

The -set systype option specifies the target environment for the loadfile being built
by the TNS/E linker. The systype attribute has no meaning for a DLL. A DLL may be
usable by a Guardian process, or an OSS process, or both, depending on how the
various parts of it were written and compiled. However, you must be aware of how the
different parts were written and compiled to use it appropriately. The target
environment does not affect anything else the linker does unless otherwise specified in
this document. The target environment is indicated within the loadfile by the
EF_TANDEM_SYSTYPE bit in the e_flags field of the ELF header.

Target Platforms

The default target environment is guardian for the linker hosted on Guardian. The
default is oss on the PC. The default on OSS is either guardian or oss, depending
on whether the object file is being created in a Guardian subvolume.

Filenames and The File Identifier

In the Guardian environment, “filename” is defined as the complete descriptor
(pathname) of \NODE.$VOL.SUBVOL.FILEID. The actual file’s name is contained in
the FILEID, the file identifier.

In the OSS environment, filename id defined as any component of the pathname, that
is /filename/filename/filename. The actual file’s name or file identifier comes after the
rightmost slash.

Sometimes the linker is required to put or pull off the file identifier of a filename, and
that means the following:

On Guardian, it is the part of the filename after the last period. If there is no

•

period in a name, the entire name is used.

On OSS, it is the part of the filename after the last slash, if any.

•

On the PC, it is the part of the filename after the last slash, backslash, or colon,

•

if any.

eld Manual—527255-009

2-2

eld Input and Output

Sometimes the linker is required to put a filename back together from its two pieces.
The linker concatenates the two pieces using a period on Guardian, a slash on OSS,
or a backslash on the PC.

A Note About MAP DEFINES

A DEFINE is a collection of attributes to which a common name has been assigned.
These attributes can be passed to a process simply by referring to the DEFINE name
from within the process. The =_DEFAULTS DEFINE is an example of such a DEFINE;
this DEFINE passes the default node name, volume, and subvolume to a process.

The DEFINE mechanism can be used for passing file names to processes; this kind of
DEFINE is called a CLASS MAP DEFINE. The following example creates a CLASS
MAP DEFINE called =MYFILE and gives it a FILE attribute equal to
\SWITCH.$DATA.MESSAGES.ARCHIVE:

1> SET DEFINE CLASS MAP, FILE \SWITCH.$DATA.MESSAGES.ARCHIVE
2> ADD DEFINE =MYFILE

Filenames and The File Identifier

Whenever your process accesses the DEFINE =MYFILE, it gets the name of the file
specified in the DEFINE. For example, when your process opens =MYFILE, the file
that actually gets opened is \SWITCH.$DATA.MESSAGES.ARCHIVE.

There are various items on the eld command line that are filenames. These include the
parameters of various options, such as -o, -l, -strip, etc., as well as filenames
that are just written directly on the command line. For such command line items, eld
checks if they begin with equal signs. If so, in the Guardian case, the linker will
immediately do the expansion of the DEFINE, so that all uses thereafter are the same
as if the expanded name had been given originally (with one special case described
below). The expansion of the name should also be done in upper-case, and the linker
will put out an informational message. If the specified string cannot be expanded as a
MAP DEFINE, that is an error. And, on other platforms, such as the PC or OSS, if a
filename parameter begins with an equal sign, that is unconditionally an error.

On the other hand, there are certain items on the command line that are not filenames,
although they look similar to filenames. In such cases, if the string starts with an equal
sign, that is always an error, even on Guardian. Examples of this include the names of
subvolumes specified in options such as -L and -rpath, and the DLL name specifed
by the -soname option.

When it comes to parameters that are symbol names, no such rules apply. An equal
sign at the start of a symbol name has no special significance to the linker.

There is a special case. In the case of the -libname (or -set libname, or ­change libname) option, usually, it is an error if the parameter is not exactly of the
form $a.b.c. However, a DEFINE can be used for this, even though a DEFINE always
expands to the form \system.$a.b.c. In these contexts, after expanding the DEFINE,
the linker also removes the system name.

eld Manual—527255-009

2-3

eld Input and Output

Output Object Files

The linker can create a new object file or update an existing one in certain ways. When
the linker is creating a new object file, by default it creates a loadfile, but the -r option
instead tells the linker to create a linkfile. The TNS/E linker can also create an import
library, as described in Creating Import Libraries on page 3-11.

When the linker creates a new linkfile with the -r option, and there was only one input
file, the output file may be considered a new version of the input file. There are two
reasons why you might do this:

To strip the file in place, with the -s or -x option.

•

To change the specified floating point type with the -set floattype option.

•

When the linker creates a new linkfile with the -r option, and there was only one input
file, the linker is required to create the new file so that it has the same fingerprint as the
original file.

The two types of ELF loadfiles produced by the linker are programs and DLLs.
These are both PIC (position independent code). The default is to create a PIC
program. The option named -call_shared means this, and so is the default for the
TNS/E linker. The option to create a DLL is -shared. The option -dll is accepted as
a synonym for -shared.

Output Object Files

eld reports an error if you specify more than one of the -call_shared, -r, and -

shared options.

When a DLL is created, its DLL name can be specified with the -soname option.
If the -soname option is used, the linker accepts whatever string is given for the DLL
name, exactly as-is, and without imposing any rules as to which strings are legal DLL
names.

If the -soname option is not specified then the DLL name is determined to be the file
identifier of the output file. The name of the output file is determined as described in

The Creation of Output Object Files on page 2-5. And, in this case, when the linker is

running on a host platform where the case of filenames is not significant (i.e.,
Guardian or the PC), the linker converts the DLL name to lower case. Note that, on
OSS, the default name for the output file is “a.out”, so the default DLL name is similarly
“a.out”, and that is true even if this is a Guardian subvolume.

The linker places the DLL name into the DT_SONAME entry of the .dynamic section

of the DLL.
The option named -dllname is accepted as a synonym for -soname.

eld reports an

error if you specify this option when not building a DLL.

A user library is a DLL that is found in a special way by programs, but otherwise is no
different from any other DLL. The -ul option is intended to be used when creating a
DLL that is used as a user library.

eld Manual—527255-009

2-4

eld Input and Output

The -ul option is synonymous with -shared plus -export_all, that is, to create a
DLL and export all its symbols. See Using User Libraries on page 3-10 for an
explanation of how the linker uses user libraries.

Certain DLLs are called implicit libraries. If the linker is creating a DLL, it can also be
told to make it an implicit library with the -make_implicit_lib option. This option

causes the linker to set the EF_TANDEM_IMPLICIT_LIB bit in the ELF header and to

impose certain other rules, as mentioned in various other places in this manual.

The Creation of Output Object Files

The name of the output object file is specified by the -o option. If the -o option is not
specified, but the -soname option is specified, then the name specified for the ­soname option is also used for the -o option.

If neither the -o nor -soname option is specified, the default output file name is
“aout” on the Guardian host and “a.out” elsewhere. Note that, in a Guardian subvolume
of OSS, the created file would actually be named “aout”, because the period
automatically goes away.

The Creation of Output Object Files

On Guardian, and in Guardian subvolumes on OSS, the linker creates object files with
a file code of 800.

Output files on Guardian are odd unstructured files. The same is true for files created
in Guardian subvolumes on the OSS host platform.

On the TNS/E OSS host platform, when a loadfile is created with OSS as its target
personality, the linker gives it mode 777 because it is executable there. In all other
cases when the linker creates an object file on any version of OSS it gives it mode 666.
These modes are octal values, and they are AND’ed with the value returned by the
umask system call.

Whenever the TNS/E linker creates an object file it first creates a work file. This file is
in the same directory or subvolume as the output object file and will have a name of

the form ZLDAFnnn, where nnn is a 3-digit integer of the form 000, 001, etc. The linker

will choose the first name of this form that is not the name of an existing file, and it is
an error if all names of this form are already taken. The linker will attempt to do this in
an atomic way so that multiple links creating output object files for the same directory
or subvolume won’t choose the same name. The linker will remove the work file if it
detects any error before the work file is complete.

The -temp_o option specifies the name of an intermediate file. If the specified name
is just the file identifier then the name is interpreted to be within the same directory or
subvolume as the output object file. If the specified name is not the file identifier then

eld reports an error if you do not specify the same directory or subvolume as the

output object file.
If no error has occurred and the -temp_o option has been specified then the linker

will rename the completed work file to this intermediate file name. If there already was
a file with the name as specified in the -temp_o option, or if for any other reason the
linker is unable to rename the completed work file to the intermediate file name, then

eld Manual—527255-009

2-5

eld Input and Output

the name of the work file is unchanged and the linker puts out a warning message.
Similarly, if the -temp_o option is not specified then the name of the work file is
unchanged.

Thus, the -temp_o option gives the user a way to specify the name of a file that will
only come into existence if the link is successful and will still be in existence if
something goes wrong when the linker tries to put the file in the designated output file
location.

Next, if there already was a file with the name of the output object file, the linker will try
to remove that file. If the linker cannot remove it, the linker will put out a warning
message saying that the output file of the link is in the location of the work file (possibly
renamed by -temp_o). If there was no file with the same name as the output file, or if
the linker was successful in removing that file, the work file is renamed to the output file
name.

The name of the output object file can be the same as the name of an input file. That
input file would therefore be removed if the link was successful.

It is possible that the linker might terminate unexpectedly, after creating a complete
work file, but before being able to rename it to the final output file name. You might
want to know where that file is, and that is the reason for the -temp_o option. In other
words, it tells the linker which name to use, so that you don’t have to search through all

files with names of the form ZLDAFnnn.

Creating Segments of the Output Loadfile

Alternatively, if you specify the -must_use_oname option, that means eld reports an
error if eld cannot delete the existing file and rename the workfile to it. This is a better
behavior if eld is called from an automated script that knows how to watch out for
errors, but not how to check for the file being left in a different place. The ­must_use_oname option cannot be specified with the -temp_o option.

Creating Segments of the Output Loadfile

A segment is a contiguous portion of memory. The linker creates the segments of the
loadfile, i.e., the text segment, the gateway segment, and the data segment(s).

Appendix A, TNS/E Native Object Files

segments, and which permissions are assigned by the linker to each of the segments.

A loadfile with callable procedures also has a gateway segment. There are two types
of gateways that the linker can create. One type is used for transitions from user mode
to exec mode, and the other for transitions from exec mode to kernel mode. All the
gateways within the same loadfile are of the same type. The linker creates the first type
of gateway, called a user gateway, if there are any procedures with the CALLABLE
attribute. It creates the other type of gateway, called a kernel gateway, if there are any
procedures with the KERNEL_CALLABLE attribute. eld reports an error if a mixture of
both of these occur among the linker’s input linkfiles.

tells which sections go into each of the

By default, the linker knows how to create the gateways.
The linker option named -instance_data, which takes a single parameter for which

there are five possibilities, tells the linker whether to create one data segment or two

eld Manual—527255-009

2-6

eld Input and Output

and what additional rules should be enforced, as shown in the following table. eld
reports an error if you specify the -instance_data option more than once with
different parameters. eld reports an error if you specify -instance_data with -r.

Table 2-1. Parameters to the -instance_data Option

Parameter Meaning

data1 Create one data segment. (This is the

Creating Segments of the Output Loadfile

default.)

data2
data2protected*
data2hidden

data1constant It is an error to have any data that would

* The data2protected parameter is supported only on systems running J06.09 or earlier J-series RVUs and H06.20
or earlier H-series RVUs.

These three cases tell the linker to create
two data segments, i.e., the “data
constant” segment and the “data variable”
segment.

need to go into the data variable segment
if we were told to create two segments.

If the loadfile being created had no data that would go into the data variable segment

then the linker sets the data1constant bit in the e_flags field of the ELF file header.

Otherwise, the linker sets the bit that corresponds to which parameter was given to the

-instance_data option. The three different values set in the e_flags field in these

cases tell the HP NonStop operating system how to protect the data variable segment.
When the -make_implicit_lib option is used, -instance_data

data1constant is imposed, and eld reports an error if you specify

-instance_data with any other parameter value.

There is no special boundary between the initialized data and the uninitialized data in
the data (variable) segment. If the last portion of initialized data happens to be zero,
the linker considers it to be within the uninitialized data, because what is called
“uninitialized” data gets initialized to zero by the operating system. That possibly
makes the size of the initialized data smaller within the object file. Based on this, the

linker will fill in the p_filesz field of the appropriate program header. On the other hand,

the linker also rounds up this value to a multiple of 4 kilobytes, thus possibly making
the size of the initialized data larger. This tells the amount of space occupied by the
appropriate segment within the loadfile, and the portion rounded up by the linker is
initialized to zero in the loadfile.

The program header of type PT_TANDEM_RESIDENT points at the .restext section,

that is, the resident code. There is no special boundary between the resident and non­resident code.

For a DLL the -t option specifies the starting address of the text segment of the DLL
in memory. If the -t option is not used then it is possible for the DLLs address to be
determined by using a DLL registry, as covered in the sub-section below.

eld Manual—527255-009

2-7

eld Input and Output

Note that this is a DLL registry under the user’s control, not the “public DLL registry”
covered in Finding and Reading The Public DLL Registry (ZREG) File on page 3-23.

If the -t option is not specified, and no DLL registry is specified, the DLL is placed at
the address 0x78000000.

If the -d option is not used, the data (constant) segment of a DLL is placed
immediately after the text segment at a 64KB boundary if it isn’t an implicit DLL, or
128KB if it is an implicit DLL. The -d option may be used to tell where the data
(constant) segment starts. eld reports an error if you specify the -d option for a DLL
without the -t option.

The two segment addresses for a program are always specified independently, with
the -t and -d options. The default value for -t is 0x70000000, and the default
value for -d is 0x08000000.

Note: In general, the -d option should not be used, because it will result in the

creation of a file that the operating system will refuse to load.
The values specified for the -t and -d options are rounded up, if necessary to a

multiple of 128KB for an implicit DLL, or 64KB for other types of loadfiles. If rounding
up is necessary, a warning message is produced.

Using a DLL Registry

eld reports an error if you specify the -t or -d option with -r.

Using a DLL Registry

The linker uses a DLL registry to manage DLL addresses so that the virtual addresses
of some or all of the DLLs being managed by a given registry do not overlap. Note that
this is a DLL registry managed by the individual user, not the “public” DLL registry
covered in Finding and Reading The Public DLL Registry (ZREG) File on page 3-23.
The linker can pick addresses on its own, or the registry can be modified by hand to tell
the linker what to do.

The -check_registry and -update_registry options tell the linker which
registry to use.

The -check_registry option is used to tell the linker how the DLL must be

•

built, giving it no choice.
The -update_registry option can make suggestions to the linker, but the

•

linker still has decisions to make, and the registry is updated as a result. If
neither option is used, the linker does not use a registry.

eld reports an error if these options are used when the linker is not building a

•

DLL.

eld reports an error if both options are used. eld reports an error if either

the -check_registry or -update_registry option is used with the -t
or -d option.

When a DLL registry is used the linker lays out data segment(s) of the DLL
immediately after the text segment, at a 64KB boundary if it isn’t an implicit DLL, or at a
128KB boundary if it is an implicit DLL.

eld Manual—527255-009

2-8

eld Input and Output

It is possible to use the DLL registry with a DLL that has two data segments, or that
has a gateway. In such cases, when this discussion of the DLL registry refers to the
“data segment”, it means a fictitious segment that is the concatenation of the data
constant segment, data variable segment, and/or gateway segment (whichever of
these segments exist). The “(unrounded) size” of this fictitious segment includes any
space that gets added before the second or third of these segments in order to make
that segment start on a 64 KB boundary.

The -check_registry and -update_registry options attempt to open an
existing registry for reading. If they succeed in opening the file, they keep it open and
locked until they are through with the file. The time that the registry file would be open,
and therefore locked, would typically be a short time for the -check_registry
option, and a long time for the -update_registry option.

If the specified file exists but cannot be opened because it is currently in use (i.e., as
far as the operating system is concerned) or locked (by the linker’s locking
mechanism), the linker will pause for a brief time and try again. That could be helpful
when several links are being done in the same place, and the other links are using

-check_registry. If these opens don’t work after several attempts, eld reports an
error.

Using a DLL Registry

The registry is a text file. In a Guardian subvolume of OSS it must be a code 180 file.
Blank lines are treated as comments, as are lines whose first two non-blank characters
are hyphens. Each of the other lines of the registry must begin with one of the
keywords explained below, and the rest of the line provides the parameters for that
keyword. The keyword and parameters are separated by blanks or tab characters.

The keyword -dllarea, if used, must be the first keyword in the file. It takes two
numerical parameters whose format is the same as the format of a <hexadecimal
number> as described in The Linker Command Stream on page 1-5. The first
parameter tells the starting address for the placement of DLLs and the second
parameter tells the ending address. Whichever one of the two addresses is smaller
determines the lower bound for DLL addresses. The other one determines the upper
bound. The one called the starting address tells at which end of this region the linker
begins placing DLLs, so that the linker can either work upward from the bottom of the
region, or downward from the top of the region. The DLLs managed by this registry
must have addresses that fit within this range, meaning that the starting address of the
DLL must be at least as large as the lower bound and the starting address of the DLL
plus its reserved size (as explained below) must be no larger than the upper bound.

If the -dllarea keyword is not used, the default is the following:

-dllarea 0x80000000 0x70000000

In other words, by default, a DLL registry manages DLLs whose addresses lie between
0x70000000 and 0x80000000, and the linker lays out DLLs starting at the higher end.

Each of the remaining lines of the registry must have the keyword -range. Each such
line provides information about a DLL. The -range keyword has three parameters:

a string, to tell the name of the DLL

•

eld Manual—527255-009

2-9

eld Input and Output

a <hexadecimal number> to tell the starting address of the DLL

•

a <hexadecimal number> to tell the reserved size of the DLL

•

Together, the starting address and the reserved size tell the total range of addresses
that this DLL, or possibly a larger version of it in the future, occupies or is intended to
occupy.

Whenever the linker opens a registry, it checks for the following errors. eld reports an
error if any of the DLL ranges listed in the registry extend outside the range of
addresses that the registry allows for DLLs. It is also an error if any of the addresses or
ranges in the registry are not multiples of 64KB if the linker is not building an implicit
DLL, or 128KB if the linker is building an implicit DLL.

The linker determines whether the registry contains an entry for the DLL being built by
comparing the name of the file being created (as specified in the -o option) against
the names listed in the registry. eld reports an error if the name is found more than
once in the registry.

Note that the name comparison mentioned in the previous paragraph is by an exact
match. For example, if you have several DLLs that you store in sibling subdirectories,

named a, b, ..., you might choose to have a single registry file that lists all the DLLs
with names relative to that parent directory, such as a/libdll1.so, etc. In that case,
you would have to spell the filename of each DLL that way in the -o option when you

were creating it, which means that you’d have to be running the linker in the parent
directory. Or, if the filenames were unique in all these directories, you might choose to
put only the last part of the name into the registry, in which case you would have to be
within the appropriate subdirectory when building the DLL. Or, even if you have all your
DLLs in one place, you still need to be consistent in how you spell their names in -o
options, for example, not saying libdll1.so the first time you build it and
./libdll1.so the next time you expect to find it in the registry.

Using a DLL Registry

When -check_registry is used eld reports an error if a registry file of the specified
name does not exist, or cannot be opened for reading, or does not have the proper
format, as described above, or if the name of the DLL being built is not found in the
registry. The entry for that DLL then tells the starting address to use.

eld reports an

error if the DLL does not fit within the size reserved for it in the registry. The registry is
not modified.

The rest of this section describes what happens when -update_registry is used.
In this case, a registry file of the specified name need not already exist. If it does not
exist then the linker creates it. If the registry file already exists

eld reports an error if

the file does not have the proper format. The DLL name need not already be listed in
the file.

If the DLL name was already listed in the file then the address listed for the DLL in the
file is a suggested address. The DLL is placed at this address if the size required for it,
including the necessary rounding but not including any room for growth, is less than
the size reserved for it in the registry. In this case the registry is not updated.
Otherwise, the linker emits a warning message, chooses an address for the DLL as

eld Manual—527255-009

2-10

eld Input and Output

described below (after, in effect, deleting the old entry for the DLL from the registry),
and updates the registry accordingly.

The -grow_limit option may only be specified if -update_registry is used. If

-grow_limit is not specified then the linker determines the reserved size of the DLL
from the following options, which are only allowed when -update_registry is used
and -grow_limit is not used:

-grow_text_amount the absolute amount by which the text may grow

•

-grow_data_amount the absolute amount by which the data may grow

•

-grow_percent the percentage amount by which the text or data may grow

•

The defaults for -grow_text_amount and -grow_data_amount are 0. The
default for -grow_percent is 10. A size is calculated for each of text and data by
first adding the corresponding “amount” option to the size of that segment (before
rounding), or adding the percentage specified by the “percent” option to the size of that
segment (before rounding), and taking the maximum of these two values. The resulting
size for each segment is then rounded up to a multiple of 64KB (or, 128KB if the linker
is building an implicit DLL), and the sum of these two sizes is the reserved size of the
DLL.

Using a DLL Registry

When the linker is choosing a new place for a DLL, because it wasn’t specified in the
registry before or didn’t fit where the the registry previously specified, and the

-grow_limit option has been given, the reserved size that the linker gives to the
new entry in the registry is the value specified in the -grow_limit option, rounded
up to a multiple of 64KB (or, 128KB if the linker is building an implicit DLL). In this case

eld reports an error if the sum of the sizes of all the segments of the DLL (including

rounding) is larger then the value specified in this option (rounded up to a multiple of
64KB or 128KB, depending on whether it is an implicit DLL).

If the DLL name was not already listed in the file, or didn’t fit in the place previously
listed for it, then the linker chooses the address for the DLL by looking for blocks of
space that are at least as large as the reserved size for this DLL, that lie within the
range of addresses that the registry allows for DLLs, and that don’t overlap the space
reserved for any other DLLs in the registry.
large enough. The linker chooses such a block that is closest to the starting address
for the registry. Thus, the linker searches upward from the lower bound of possible
addresses, or downward from the upper bound, depending on how the bounds were
specified for this registry. The registry is updated to tell the address and reserved size
of the new DLL.

If the user wishes to specify an address for a new DLL in the registry, rather than
letting the linker choose the address, the registry file can be edited by hand. It is
necessary to specify both the starting address of the DLL and its reserved size, as
multiples of 64KB. Or, if this is a registry that is being used for implicit DLLs, then they
should be multiples of 128KB. It is also possible to change these values for a DLL
already listed in the registry. It is permissible to edit a registry so that some DLLs have
overlapping address ranges. When the linker picks an address on its own it requires
that this DLL not overlap any other ones in the registry, but the linker doesn’t check

eld reports an error if there is no block

eld Manual—527255-009

2-11

eld Input and Output

whether entries already in the registry overlap. Whenever a DLL registry is updated by
the linker and the DLL had previously been mentioned in the file, the old entry is
replaced by the new one so that the DLL is not mentioned more than once in the
registry.

A new registry file is always created, mostly following the same rules as given earlier in

The Creation of Output Object Files on page 2-5.

One difference is that the name of the work file is ZLDARnnn rather than ZLDAFnnn
and the name of the intermediate file, if desired, is specified by the -temp_r option
rather than the -temp_o option. Also, there is a -must_use_rname option, instead
of -must_use_oname.

Also, if the linker cannot create a new DLL successfully (i.e., terminates in error before
that point), then the linker does not modify the existing DLL registry. However, once the
linker has succeeded in creating its output DLL, the linker will not consider any
subsequent problems with the DLL registry to be errors. If the linker cannot update the
registry as desired, that will only be reported as a warning.

Note that the linker must first read an existing private DLL registry before it writes out a
new version of it. As explained above, if the linker can’t read it, eld reports an error.
So, the -temp_r and -must_use_rname options are only relevant to situations
where the linker had permission to read the existing private DLL registry, but not delete
it.

Input Object Files

Input Object Files

TNS/E linkfiles have no object file version number associated with them.

Loadfiles have a version number stored in the .tandem_info section, placed there by

the linker. At the present time the version number is zero. When the linker reads a
loadfile for any reason the linker considers it an error if the loadfile contains a version
number different from zero. This version checking is disabled by the ­no_version_check option.

On the Guardian platform the linker does not check that object files have the proper file
code. If the file was not the right kind of file, the linker would soon realize it in some
other way.

How the Linker Finds Its Input Files and Creates the .liblist

Section

The linker locates linkfiles, archives, DLLs, and import libraries based on items
specified in its command stream. This section provides the rules for doing this. As part

of this process, the linker also creates the .liblist section for its output loadfile.

See Using Archives on page 2-16 for an explanation of how the linker decides which
files to use from an archive.

eld Manual—527255-009

2-12

eld Input and Output

See Presetting Loadfiles on page 3-5 for an explanation of how the linker also finds

indirect DLLs by using the .liblist sections of other DLLs that it has already found, and

for how the linker finds the import library that represents the implicit DLLs.

See Using User Libraries on page 3-10 for an explanation of how the linker finds user
libraries.

The linker does not have any built-in set of DLLs for which to look, other than the
import library that represents the implicit DLLs. Although other DLLs may typically be
needed for C/C++ runtime support, they must be specified explicitly in the linker’s
command stream. The user who invokes the linker indirectly through the C/C++
compiler may be unaware of this, because the C/C++ compiler automatically adds the
appropriate command stream items when it invokes the linker.

The linker looks for import libraries the same way it looks for DLLs. Unless mentioned
otherwise, when this section explains how the linker finds DLLs, the same remarks
apply to import libraries. The linker accepts archives, DLLs, or both, according to the
following options:

-b static - only accept archives, not DLLs

•

Input Object Files

-b dllsonly - only accept DLLs, not archives

•

-b dynamic - accept both archives and DLLs

•

These options form a three-way switch, selecting one of three modes for the linker at a
given point in the command stream. These options can be specified multiple times in
the command stream, each time setting the mode for subsequent items in the
command stream until the mode is changed again. At the beginning of the command
stream the mode is -b dynamic.

An item in the command stream that causes the linker to find a linkfile, archive, or DLL
is one of the following three things:

a name specified directly in the command stream

•

a -l option whose parameter is a file identifier

•

a -l option whose parameter is not a file identifier

•

The definition of file identifier is given in Filenames and The File Identifier
The -lib option is a synonym for -l, and may be preferred because the -lib

option is not case-sensitive, whereas -l is a different option from -L.

The linker uses one of the following two methods to find a file, based on the way it was
specified in the command stream:

on page 2-2.

for a name specified directly in the command stream, or for a full filename

•

specified in a -l option, the linker opens the file normally.
for a file identifier specified in a -l option, the linker searches for the file.

•

Opening a file normally means that the linker tries to open the name exactly as it is

specified. This means that the name may be interpreted relative to the current directory

eld Manual—527255-009

2-13

eld Input and Output

or subvolume, as is normally done for the corresponding host platform. eld reports an
error if the file does not exist, or if the linker cannot open it for reading.

In the case that the name was specified directly in the command stream, the file can be
a linkfile, archive, or DLL. In the case that the name was specified as a full filename in
a -l option, the file must be an archive or DLL. In either case, if -b static is in
effect then eld reports an error if the file is a DLL, and if -b dllsonly is in effect
then eld reports an error if the file is an archive.

The linker searches for a file by performing several steps. Most of these steps involve

looking for the file in a given directory or subvolume, although one step is a special
way to look for public DLLs. When the linker is looking in a directory or subvolume
there are certain filenames that it expects to find. If a desired file doesn’t exist, or if it
does exist but the linker cannot open it for reading, then the linker continues without
warning. More details of what the linker does during the search are provided in the
following sub-sections of this manual.

By default, if the linker gets to the end of its search without finding a file to satisfy a -l
option, eld reports an error. However, the -allow_missing_libs option tells the
linker that it is not an error unless this happens when the current mode is -b static.
If it isn’t an error, the linker instead emits an informational message.

Input Object Files

When the -r option is specified, telling the linker to create a linkfile rather than a
loadfile, the linker looks for archives and DLLs the same way as in other cases, but
then the DLLs are ignored.

Informational messages tell the file names of all the archives and DLLs that were
opened by the linker, saying for each one whether it is an archive, a DLL, or an import
library. If it is an import library, the message tells whether the import library is complete
or incomplete.

Whenever the linker finds an import library from the command stream, it checks
whether the DLL name within this file is “__IMPLICIT_LIB__”. If so, it is recognized to
be the import library that represents the implicit libraries, and it is used as the last item
in the search list, as described in Presetting Loadfiles on page 3-5. It is always an
error if the linker finds a DLL, rather than an import library, whose DLL name is
“__IMPLICIT_LIB__”.

If the -make_implicit_lib option is given, eld reports an error if any of the DLLs
or import libraries that the linker finds in the command stream do not have the

EF_TANDEM_IMPLICIT_LIB bit set in their ELF headers. Also, when ­make_implicit_lib is used, eld reports an error if the linker finds an import library

whose DLL name is “__IMPLICIT_LIB__”.

The linker creates the .liblist section of its output loadfile. The .liblist section contains

one entry for each DLL (or import library) obtained from the command stream,
regardless of the method used to find it. The entry tells the name of the DLL, as

obtained from the DT_SONAME field of the DLLs .dynamic section. There is no
requirement that the name found within the DLL, and therefore stored in the .liblist

section, match the name that was used to find the DLL from the command stream.

eld Manual—527255-009

2-14

eld Input and Output

However, to simplify build processes, the user may find it convenient for these names
to be the same.

The .liblist section does not contain an entry corresponding to the user library, does not

contain an entry for the import library that represents the implicit libraries, and does not
contain entries for DLLs that the linker finds indirectly.

When the search to satisfy a -l option does not succeed, and this is not an error
(because the -allow_missing_libs option was specified and the mode is not -b
static), the .liblist section will still contain an entry for that -l option. In other words,
it is assumed that the name was intended to be a DLL as opposed to an archive.
Because the linker doesn’t have a DLL name to put into the .liblist section entry, it
instead will put in the string that was the parameter to the -l option. The linker also
sets the LL_NOT_FOUND bit in the .liblist section entry to identify this as an entry for a

-l option for which the search did not succeed.
Each .liblist section entry tells if it is reexported. The -reexport and -no_reexport

options form a two-way switch, selecting one of two modes for the linker at a given
point in the command stream. These options can be specified multiple times in the
command stream, each time setting the mode for subsequent items in the command

stream until the mode is changed again. When -reexport is in effect, the .liblist

section entry for a DLL found in the command stream says that it is re-exported. When

-no_reexport is in effect it is not re-exported. At the beginning of the command
stream the mode is -no_reexport. eld reports an error if you use either of these
options when not building a DLL.

Input Object Files

The following rules apply to situations where the same file is found several times in the
command stream:

It is not explicitly called out as an error if the same linkfile is specified more

•

than once in the command stream, but it may lead to the error of multiply
defined symbols, as explained later in Accepting Multiply-Defined Symbols on
page 3-17.

It can be useful to specify the same archive more than once in the command

•

stream, as explained later in Using Archives

With regard to DLLs, a requirement is that the same DLL name cannot be

•

present more than once in the .liblist section. The rule is that, if the linker finds

the same DLL more than once in the command stream, where “same” means
that they have the same DLL name, the linker ignores all the instances after
the first one. However, the linker also checks whether the DLL was found with
the same export digest each time. If not, a warning message is provided.

When a user library is used by the linker, it is treated like an additional DLL at

•

the beginning of the command stream. However, if the DLL name within the
user library matches the name of another DLL found later, that other DLL is still

used, and gets a .liblist entry 7 , although the linker puts out a warning

message about this.

on page 2-16.

eld Manual—527255-009

2-15

eld Input and Output

The rules above, about finding the same DLL name more than once, also apply to the
special DLL name “__IMPLICIT_LIB__”.

Using Archives

An archive is a file that contains copies of linkfiles. The linker looks for files within the
archive to be used by the link. Linkfiles in the archive are used if they define global
symbols that are currently known about, but undefined, at this point in the command
stream. In each case, once the linker decides to use a file from the archive, that entire
file is used the same way it would be used if it had been specified directly in the
command stream.

It can be meaningful to specify the same archive more than once in the command
stream, because each time the linker opens the archive it only looks for linkfiles that
resolve symbols that are needed at that point.

When a linkfile is brought in from an archive, that can lead to additional needed
symbols. The archive is searched repeatedly to find such symbols. However, once the
linker has moved on to the next token in the command stream, this archive will not be
looked at again unless it is specified again in the command stream.

Using Archives

The -u option is used to specify the name of a symbol for which eld should look in
archives in the command stream, if eld had not already seen a definition of this
symbol before the archive was encountered. Note that this is similar to having a
hypothetical linkfile at the start of the command line that declared such a symbol
without defining it. However, one difference is that, when a symbol really does get
declared in a linkfile, that declaration tells if the symbol is globalized or not, but the

-u option does not imply anything about whether the symbol is globalized.
The -all option tells the linker to unconditionally use all linkfiles found in archives,

rather than only using those that provide needed symbols. The -none option turns
this off, so that files found in archives are used only if they provide needed symbols as
described above. These options form a two-way switch, selecting one of two modes for
the linker at a given point in the command stream. These options can be specified
multiple times in the command stream, each time setting the mode for subsequent
items in the command stream until the mode is changed again. At the beginning of the
command stream the mode is -none. One use of -all is to convert an archive into a
DLL by telling the linker to build a DLL that contains all the same files as are present in
the given archive.

The option -include_whole is accepted as a synonym for -all, and

-no_include_whole as a synonym for -none.

In general, users having 32-bit and 64-bit versions of their code are recommended to
maintain two separate versions to avoid confusion. For the archives, it is
recommended that the users do not mix up the 32-bit and 64-bit object files in the
same archive. Typically, a user has two archives with similar contents, one for the 32-
bit and the other for the 64-bit case. If the user links on to the OSS, two archives
can have the same name but, if the 32-bit archive is placed into /lib, /usr/lib,
or /usr/local/lib, while the 64-bit archive is placed into /lib64, /usr/lib64,

eld Manual—527255-009

2-16

eld Input and Output

or /usr/local/lib64 then, the same -l option in the linker verifies the desired one
based on the type of link created. Otherwise, the user can decide the naming
convention for the archives and formulate the linker to find the right version.

Archives are a method of making loadfiles smaller, because the linker will automatically
bring into the link only those members of the archive which are needed. Archives are
also a way of packaging together multiple linkfiles, as an alternative to using the -r
option.

The Steps in Looking for Archives and DLLs

The linker performs the following steps, in the order given, to search for an archive or
DLL:

1. The linker first looks in the directories or subvolumes whose names are

specified in -first_L options in the command stream, in the same order that
those options occurred in the command stream.

2. The linker next looks for public libraries. However, the linker does not do this if

the -r option is specified or if -b static is in effect.

Using Archives

3. The linker next looks in the directories or subvolumes whose names are

specified in -L options in the command stream, in the same order that those
options occurred in the command stream. The -libvol option is a synonym
for -L, and preferred because the -libvol option is not case- sensitive,
whereas -L is a different option from -l.

4. On OSS, the linker looks in a list of standard places. If the linker is building a

64-bit object, or if the -alf option is processing a 64-bit loadfile, then the first
three places in this list are /lib64, /usr/lib64 and /usr/local/lib64.
In all other cases, the next three places in the list are /lib, /usr/lib, and
/usr/local/lib. Each of the above names is prefixed with the contents of
the COMP_ROOT environment variable, if the variable is defined.

5. Finally, on Guardian or OSS, if the linker is building a 64-bit object or if the

-alf option is processing a 64-bit loadfile, the linker looks into the
$SYSTEM.YDLL and in all other cases the linker looks into $SYSTEM.ZDLL.

However, the linker does not perform these actions if the -r option is specified
or if -b static is in effect.

The following sub-section tells the rules that are used for looking for public libraries
(step 2 above), and the sub-section after that tells what the linker does when it is
looking through other directories or subvolumes (all the steps above other than step 2).

If the -nostdlib option is specified, steps (2), (4), and (5) in the above list are
skipped, so that the linker would only look in the places specified by -first_L or -L
options. The option -no_stdlib

The same search method is used for all searches. For example, it doesn’t matter
whether some of the -L options came later in the command stream than the -l
option for which the search is being performed.

is accepted as a synonym for -nostdlib.

eld Manual—527255-009

2-17

eld Input and Output

The linker does not make use of any environment variables other than COMP_ROOT.
When eld is creating a new object file X from a set of linkfiles, or processing a loadfile

X with the -alf option, it is desired that DLL’s of the appropriate data model match the
data model of X. Therefore, if X is neutral then it is desired that all the DLL’s used are
neutral, and if X is not neutral then it is desired that all the DLL’s used are either neutral
or same as X. During a search, if a DLL that is not desired is encountered, the search
continues. If the search function later finds an archive or a DLL which is desired, the
previously found DLL that was not desired is ignored. If the search does not succeed,
the DLL found earlier is used, even though it is not desired. A warning is issued if a
DLL of the undesired model is used.

Finding Public DLLs

This section explains how the linker looks for a public DLL based on the file identifier.
(The file identifier may have been specified in a -l option in the command stream, or
may have been found in the liblist of some other DLL).

As described in Finding and Reading The Public DLL Registry (ZREG) File on
page 3-23, the linker may or may not have located the public DLL registry file. If the
linker did not locate the public DLL registry file, it does not look for public DLLs. (It
continues to look for this DLL in other ways). The rest of this section assumes that the
linker did locate the public DLL registry file.

Using Archives

The linker verifies whether the file identifier matches with one of the public DLL
filenames found in the public DLL registry. If there is no such match and the linker is
either creating a 64-bit object file or the -alf option processes a 64-bit loadfile. The
linker verifies whether the name added with prefix “y” and suffix “DLL”, matches one of
the public DLL filenames found in the public registry. Later, the linker verifies whether
the name added with prefix “z” and suffix “DLL” matches the public DLL filenames
found in the public DLL registry.

Note. All of these matches are case insensitive.

If the linker does not find the file in the appropriate place as described above, or finds it
but cannot open it for reading, or if the file is not a DLL,

eld reports an error.

If the linker is creating a 64-bit object file or the -alf option is processing a 64-bit
loadfile, and if a file exists with the name lib instead of “y” prepended, and y.so
instead of “DLL” appended, then linker uses this file. If a file exists, with the name
lib instead of “z” prepended and .so instead of “DLL” appended, then linker uses
this file. The linker considers it an error only if these files do not exist, or are not DLLs.

Note. There is also an exception which applies to platforms other than Guardian.

In other words, as a result of the special cases described above, it is possible to put a
copy of the real zreg file into a location on the PC or OSS so that it lists the public
DLLs with names like zcredll or ycredll, etc., but in the same location. Instead of
having files named zcredll or ycredll, etc., you can rename them as:
libcre.so, or libcrey.so, and so on. eld does not consider it as an error when

eld Manual—527255-009

2-18

eld Input and Output

you enter the -l cre option or if it processes a DLL and as a result finds the name:
zcredll or ycredll in the liblist of the other loadfile.

The Rules to Find Files

This section tells the rules that the linker uses to decide which files to try to find and
open in each directory or subvolume that it is searching. This applies to all the steps
followed by the linker in searching for an archive or DLL, other than the special step for
the public DLLs.

This is the algorithm that the linker uses to look for a file within a directory or
subvolume:

First, the linker looks for a file with the name as it was given in the -l option.

•

Next, if the platform is not Guardian, and this is not a directory on OSS that is a

•

Guardian subvolume, and -b static is not in effect, the linker looks for a
filename of the form libx.so, where x was the name specified in the -l
option. This rule is not applicable for instances where the linker is searching for
an indirect DLL. While searching for an indirect DLL, eld searches files with
the name specified in the .liblist section.

Using Archives

Finally, if the platform is not Guardian, and this is not a directory on OSS that is

•

a Guardian subvolume, and -b dllsonly is not in effect, the linker looks for
a filename of the form libx.a, where x was the name specified in the -l
option.

For example, on OSS, if the linker is given the -l ab option, and it is searching
through an OSS directory that is not a Guardian subvolume, it may find ab, libab.a,
or libab.so. Or, if given the -la.b option, it similarly may find a.b, liba.b.a, or
liba.b.so. On the other hand, if it is searching through a Guardian subvolume on
OSS, and it is given the -lab option, it will only look for ab, not libaba or libabso.
If given the -la.b, it won’t look for any of these things in a Guardian subvolume.

When the linker opens a file under the name as it was given in the -l option, if -b
static is in effect then
is in effect then eld reports an error if the file is an archive. When the linker opens a file
with the name libx.so,
opens a file with the name libx.a,

The linker does not check whether some of the directory or subvolume names are
syntactically incorrect. It simply discovers that the files with the names constructed as
explained above can’t be opened, and then continues. For instance, the user may find
it convenient to use the same search path on several platforms, where the search path
contains some names valid for one host platform, and other names valid for another
host platform. On each host platform, the names valid for that platform may do
something meaningful, and the other ones would be ignored.

eld reports an error if the file is a DLL, and if -b dllsonly

eld reports an error if the file isn’t a DLL. When the linker

eld reports an error if the file isn’t an archive.

eld Manual—527255-009

2-19

eld Input and Output

Using Archives

eld Manual—527255-009

2-20

3 Binding of References

This section contains the following topics:

Overview -an overview of symbol resolution and code relocation.

•

Presetting Loadfiles - the process of resolving references to DLLs at linktime.

•

To Preset or Not to Preset, and Creation of the LIC - the linker’s rules for

•

presetting.

Handling Unresolved References - what happens if a symbol is not found in any

•

loadfile in the linker’s search list?

Using User Libraries - introduces the libname options.

•

Creating Import Libraries - three types are available.

•

Ignoring Optional Libraries - a command stream toggle is available.

•

Merging Symbols Found in Input Linkfiles - merges the symbol information from

•

the input files into its output file.

Accepting Multiply-Defined Symbols - how to accept multiple definitions for a

•

symbol?

Using the -cross_dll_cleanup option - reduces the total size of a program and the

•

private DLLs that are used by a process.

Specifying Which Symbols to Export, and Creating the Export Digest - to export

•

global and defined symbols.

Public Libraries and DLLs - two types, namely implicit and explicit.

•

The Public Library Registry - lists all public DLLs by name.

•

Finding and Reading The Public DLL Registry (ZREG) File - how the linker finds

•

the file.

Overview

The primary job of the linker is to bind abstract (symbolic) names to real addresses.
For example, as a programmer you can use the name getfile in one module, while
the linker binds that to “a location 512 bytes from the start of module iosys”. This is
known as symbol resolution.

The other closely related function of
assemblers generally create each file of object code with the program address starting
at zero, an address you are unlikely to be able to use. Furthermore if a program is
created from multiple subprograms, all the subprograms have to be loaded at non­overlapping addresses. These addressing problems are solved by relocation, the
process of assigning load addresses to the various parts of the program, adjusting the
code and data in the program to reflect the assigned addresses.

eld is that of relocation. Compilers and

eld Manual—527255-009

3-1

Binding of References

The functions are related because the linker can use symbol resolution to handle
relocation, by assigning a symbol to the base address of each part of the program then
treating the relocatable addresses as references to the base address symbols.

In the case of the HP NonStop operating system compilers; in TNS/R the addresses
started at zero and incremented for each section, in TNS/E all section addresses start
at zero, they don’t really contain addresses but rather contain section offsets.

eld is concerned with cases where the compiler or assembler does not know the

ultimate contents that the object file should contain for symbolic references. Such
cases are listed in the relocation tables that the compiler or assembler creates in
linkfiles. When -r is specified, the linker creates new linkfiles with the same kinds of
relocation tables.

This section considers how the linker creates a loadfile.

In order to fill in the proper values for symbolic references, the linker matches up
symbols across linkfiles, determines runtime addresses for the symbols defined in this
loadfile, and searches other DLLs to resolve references to symbols not defined within
the current object file. The loadfile that is built by the linker tells rld what needs
further examination when the loadfile is brought into virtual memory. The addresses
chosen by the linker are called the preferred addresses for this loadfile. A program is
always loaded at its preferred addresses, but that is not necessarily true for a DLL.

Overview

Here are two examples of references:

A data item that is a pointer, initialized with the address of another data item. The

•

compiler or assembler doesn’t know the final address to put in, so it creates a
relocation table entry for this data item. The linker may fill in a value, but in any
case it propagates the same type of relocation table entry to the loadfile for rld to
use.

An instruction that refers to some data item. This is different from the case above

•

because only the linker can modify executable code, not rld. The compiler or
assembler may generate code that looks up the address of the symbol in a data
location whose address is calculated by adding a 22-bit offset to the GP register,
and it creates a relocation table entry accordingly. The linker allocates that data
location as part of the .got section and updates the code so that it contains the

right

22-bit GP-relative offset to reach the corresponding .got section entry. The linker
may also fill in a value in the .got section entry, but in any case it puts information
into the object file so that rld knows how to fill in or update the .got section entry

at load time.

There are various relocation types which tell the linker how to modify a given location

in code or data after it knows the address that need to be represented there. We often
say that the linker “fills in the address of the symbol at the relocation site”, but that isn’t
precisely correct. Depending on the relocation type, it may the actual address of the

symbol, or it may be something else, such as the GP-relative offset of the .got entry

that contains the address of the symbol, and so on.

eld Manual—527255-009

3-2

Binding of References

The way references are fixed up across loadfile boundaries depends on the import
control of the loadfile being built. This controls how the search list is created, both at
link time and at load time, to find the DLLs that are needed to resolve symbols
referenced in the loadfile.

There are three choices for this, set by the following options:

-b localized (this is the default) means “localized”. The searchlist for the loadfile at link

time and load time is:

loadfile itself

•

If the loadfile is a program and has a user library, that user library.

•

a breadth-first transitive closure of re-exported liblist-specified DLLs.

•

DLLs specified in the liblist.

•

This is the the HP NonStop operating system default and gives you the most control
on how your undefined references are resolved at runtime.

-b globalized means “globalized”. The searchlist for the loadfile at link time is the

same as that of “localized” except that the transitive closure does not include re­exported DLLs. At load time the searchlist order is as follows:

Overview

The program

•

If the program has a user library, that user library.

•

The liblist of the program

•

a breadth-first transitive closure of liblist-specified DLLs

•

Other dynamically-loaded DLLs

•

The key thing to remember is that a globalized loadfile can have its own definitions
preempted by another loadfile. This is the UNIX default behavior.

-b semi_globalized or -b symbolic means “semi-globalized”. It is basically the

same as -bglobalized except that the loadfile itself is at the head of the searchlist at
load time. That means that its definitions cannot be preempted.

All three possibilities are allowed, whether building a program or a DLL, although for a
program the semi-globalized case means the same thing as globalized.
error if more than one of these options is specified. If the -make_implicit_lib
option is given, eld reports an error if you specify an import control other than
localized.

The import control is stored in the EF_TANDEM_IMPORT_CONTROLS bits of the
e_flags field of the ELF header of the loadfile being built. This manual explains how

these options affect the linker’s actions, but does not explain all the details of how they
affect what rld does.

eld reports an

Do not confuse these uses of -b with the other uses of -b described earlier in How

the Linker Finds Its Input Files and Creates the .liblist Section on page 2-12.

eld Manual—527255-009

3-3

Binding of References

The linker does not necessarily know the proper load time values to use for addresses,
because things can change between link time and load time for reasons such as these:

The DLL currently being built, or the other DLLs to which it refers, will not

•

necessarily be loaded at the same (preferred) addresses as those assumed by the
linker.

The other DLLs to which the current loadfile refers may not be the same DLLs

•

used at runtime, because they might be updated in the interim. Thus, a given DLL
may no longer provide the same set of symbols, or it may provide the same
symbols but at different addresses. This updating of DLLs may also change which
DLLs are indirectly found.

Although the same DLLs may be in the same places at load time as at link time,

•

different ones may be used because rld looks for them with different path lists.

Also, the rules that are used for binding references at load time are not rules that could
be completely implemented by the linker, even if things didn’t change as described
above. For instance, it is possible for a reference from a globalized or semi-globalized
DLL to be resolved in the main program at load time, but the linker does not see the
main program when it is building that DLL. The rules are such that, if things don’t
change as described above, and if the linker is creating a main program or a localized
DLL, then it will search the same DLLs, and in the same order, as rld.

Overview

Some symbols are exported by the loadfile that contains them, and some are not. Only
the exported symbols are visible to other loadfiles.

The linker fills in all references to symbols that are defined in the same loadfile, using
the address of the symbol within this same loadfile.

In some cases what the linker fills in may need to be modified by rld, but the linker
still guarantees to fill in all these references that were within the same file. rld may
be able to decide that this much of what the linker did was correct, and therefore avoid
the need to recalculate those references at load time. Or, rld may recalculate the
references, because it wasn’t sure that what the linker did was correct, and in such
cases it can still be advantageous if the linker was correct.

The linker also may fill in other references, to symbols not defined within this same
loadfile. In particular, the linker may do this for symbols that are not globalized
symbols, and that process is called presetting. References to globalized symbols are
not filled in, and do not generate errors or warnings. When the linker fills in references
to undefined symbols rld may again be able to decide that what the linker did was
correct, and therefore avoid additional work at load time.

There is a concept that goes under various names, such as “delayed binding”, “lazy
evaluation”, etc. This refers to the situation where there can be procedure call
references that are purposely not resolved at link time, or even at load time. Instead,
the first time the procedure is called, the rld runtime support resolves its address. HP
NonStop systems do not support this capability.

eld Manual—527255-009

3-4

Binding of References

Presetting Loadfiles

This section discusses how the linker presets a loadfile. Except as mentioned
otherwise below, import libraries are used the same way that DLLs are, and remarks
made here about DLLs in the search list also apply to import libraries in the search list.

The search list begins with the loadfile itself. Next, for a program that has a user library,
comes the user library. The user library mostly acts the same as any other DLL, except
for its special placement at this point in the search list. After that come the entries in

this loadfile’s own .liblist section, namely, the DLLs that were obtained from the

command stream, in the order they were found in the command stream.

Then, each DLL that has already been placed into the search list after the loadfile itself

can specify other DLLs in its .liblist section. The linker finds these other DLLs by using
the names in the .liblist section. The linker performs a breadth-first traversal of all these
.liblist sections in order to add more entries to the search list. The names added to the
search list after the .liblist entries of the loadfile itself are called the indirect DLLs. A

DLL is only added to the search list if its DLL name is different from all of those already
in the search list. If the loadfile being built is localized then the traversal to find indirect

DLLs only pays attention to .liblist section entries that are re-exported. The linker
makes use of the DLL names found in one .liblist section in order to search for other

DLLs, but does not check that the DLL name found within a DLL matches the name
that was used to search for it.

Presetting Loadfiles

The same kinds of rules that apply to DLLs found directly in the command stream, as
given in How the Linker Finds Its Input Files and Creates the .liblist Section on
page 2-12, also apply to indirect DLLs. This includes the following things:

The rule that, when the -make_implicit_lib option is used, all the DLLs that

•

are found must be implicit.

The rules about multiple DLLs with the same DLL name.

•

The rules about which informational messages to write out.

•

The rules about what to do if a search completes without finding a DLL.

•

The above rules about an indirect DLL are not enforced when the linker does not look
for that DLL. More specifically:

The linker does not look up a name found in a .liblist section entry if that entry is

•

not reexported and the linker is building a localized file.

The linker need not look up names in .liblist sections after it has decided that it is

•

neither going to preset nor check for unresolved references. (But the linker is
allowed to continue looking for DLLs in this case and do the usual checks on
them.)

Finally, if the -make_implicit_lib option has not been specified, the linker tries to
add the import library that represents the set of implicit libraries to the end of its search
list.

eld Manual—527255-009

3-5

Binding of References

There are several ways that the linker may find the import library that represents the
implicit libraries. Regardless of how the import library that represents the implicit
libraries is found, the linker always uses it the same way, placing it at the end of the
search list.

The linker may have found the import library that represents the implicit libraries from
the command stream, such as described in How the Linker Finds Its Input Files and

Creates the .liblist Section on page 2-12. The linker recognizes it as the import library

that represents the implicit libraries because it has the special DLL name
“__IMPLICIT_LIB__”. Note that it doesn’t matter where it was found in the command
stream, because it any case it is placed at the end of the search list.

In the previous paragraph, found “from the command stream” means that the linker
found it during the same process that the linker uses to find all the other DLLs, those
that come directly from the command stream and those found indirectly through entries
in liblists. If, during this process, an import library that represents the implicit libraries is
found more than once, the rules that are followed are the same as those followed when
that situation comes up for other DLLs. In particular, it is not an error, and the first
instance is the one that the linker will use, but if multiple occurrences of this library are
found via non-identical export digests then a warning will appear.

Presetting Loadfiles

If the linker has not found the import library that represents the implicit libraries from
the command stream, it may also determine its name by a system call.

If the linker still has not found the import library that represents the implicit libraries, but
it has found a public DLL registry file the linker next looks for a file named zimpimp in
the same subvolume or directory as the public DLL registery file. On OSS, where case
matters, zimpimp is lower case. If that file does not exist, or the linker can’t open it for
reading, the linker continues processing.

If the linker finds the import library that represents the implicit libraries via the above
process, and successfully opens it, then eld reports an error if the file is not a DLL, or if
the DLL name within the file is not “__IMPLICIT_LIB__”.

If the linker has not found an import library that represents the implicit libraries by the
process described above, and has gotten to this point without considering it an error,
then the linker gives a warning message.

After constructing the search list the linker looks for each required symbol by searching
through each DLL in the list, stopping at the first DLL that exports a symbol of that
name. The address specified for the symbol in that DLL is the address that is used to
resolve references to the symbol. Or, if the relocation type says that the address of the
official function descriptor is required, the linker would require that the target symbol be
a procedure and then would fill in the address of the official function descriptor rather
than the address of the procedure itself.

eld Manual—527255-009

3-6

Binding of References

To Preset or Not to Preset, and Creation of the LIC

To Preset or Not to Preset, and Creation of the
LIC

LIC is the ‘Library Import Characterisation’, a section in the object file that encodes
information about the current loadfile, plus each DLL or import library that was used to
do the presetting, in the search list order, noting its export digest and whether it was
used to resolve any references. The LIC is essentially a data string that characterizes
the information used by a linker or loader to bind the global symbols of a particular
loadfile. If the same loadfile is bound on two occasions, and its LIC has not changed,
the two bindings are the same. Thus it is possible to reuse a set of bindings if it has the
same LIC as that determined for this loadlfile in the presence of the other loadfiles with
which it is being loaded.

By default, the linker tries to preset the loadfile that it is creating. The following are
reasons why the linker will decide not to preset:

The linker will not preset if the -no_preset option is specified.

The linker will not preset if there is any address overlap among the DLLs or import
libraries in the search list, including this file itself. If there are any overlaps then the
linker emits a warning message. The linker always checks for this among the DLLs and
import libraries that it has opened, even if it is not trying to preset. However, the linker
does not check for overlap against the import library that represents the set of implicit
libraries (because, it can be assumed that the implicit libraries have been correctly built
in a separate place). Also, when some DLL has the same filename as the user library,
and their memory segments overlap, the linker does not consider that a reason to stop
presetting.

The linker will decide not to preset if it was unable to locate an item specified in a -l
option in the command stream or in a .liblist section entry of a DLL.

The linker will decide not to preset if this is a program that has a user library, but the
linker was unable to open the user library.

The linker will decide not to preset if it encountered any incomplete import libraries.
The linker will also decide not to preset in certain cases if there are unresolved
references, as explained in Handling Unresolved References

The linker sets the EF_TANDEM_PRESET bit in the e_flags field of the ELF header of

the loadfile to tell that it was preset.

on page 3-8.

When the linker presets a file it calculates the LIC and stores it in the .lic section. The

LIC encodes information about this loadfile itself, plus each DLL or import library that
was used to do the presetting, in the search list order, noting its export digest and
whether it was used to resolve any references. Thus, the LIC begins with an entry for
this loadfile itself, then has an entry for the user library if this is a program that has a

user library, then has entries for each of the elements of the .liblist section, then has

entries for each of the additional elements the linker found by pursuing the transitive

closure of .liblist sections, and then has an entry for the import library that represents

eld Manual—527255-009

3-7

Binding of References

the implicit libraries, if the linker found that library. If there was a DLL with the same
filename as the user library, then that DLL gets no LIC entry.

Note that, for each entry in the .lic, there is a bit that tells whether any references were

actually resolved by symbols exported from that DLL. The linker does not put out any
warning messages about DLLs that were “not used”. It is actually quite difficult to
decide which DLLs are “used”, because DLL A may indirectly bring in DLL B whose
symbols are used, even if that wasn’t true of DLL A. And, even that doesn’t mean that
DLL A was really “needed”, because there could also be other DLLs that similarly
cause DLL B to get brought into the link. (For ideas on related linker features, see

Ignoring Optional Libraries on page 3-14.)

The linker makes the .lic section larger than necessary so that it may be possible for
the object file to be modified by the -alf option when the LIC has to increase in size.

Even when the linker is not presetting it still creates the .lic section in a loadfile. The
section has no contents in this case, but it provides space for a subsequent -alf

option to create a LIC.
The -must_preset option tells the linker that it must be able to preset, or else it is to

be considered an error. eld reports an error if you give -must_preset with

-no_preset. Otherwise, if the linker can’t preset, and the -no_preset option was
not used, the linker generates a warning message.

Handling Unresolved References

Handling Unresolved References

This section discusses what the linker does when it is trying to bind a reference to a
symbol and that symbol is not found in any loadfile in the linker’s search list.

If an undefined symbol is mentioned only in the symbol table, with no references to it
from relocation tables, the linker continues processing. Checking for unresolved
references is only concerned with symbols that have references from code or data.

The treatment of an unresolved reference depends on whether the target symbol was
expected to be code or data. The linker knows this based on the symbol type listed for
the symbol in the ELF symbol table in the linkfile that refers to it. STT_OBJECT means
that it is data, and STT_FUNC means that it is code. No other possibilities are allowed.

The -unres_symbols option tells the linker how to treat unresolved references. It
takes a parameter value that is one of the following:

error - treat unresolved references as errors

•

warn - put out warning messages about unresolved references

•

ignore - be silent about unresolved references

•

-error_unresolved is supported as a synonym for -unres_symbols error,
and -warning_unresolved as a synonym for -unres_symbols warn.

When eld is building a new loadfile and a public DLL registry has not been found the
default for the -unres_symbols option is warn. On the other hand, if a public DLL

eld Manual—527255-009

3-8

Binding of References

registry has been found then the default for the -unres_symbols option is error. In
other words, eld only thinks it is unreasonable to have unresolved references if the
public DLL registry has been found.

On the other hand, regardless of what the default would have been, and regardless of
whether the -unres_symbols option actually was specified, the linker imposes ­unres_symbols ignore in the following cases:

If the -allow_missing_libs option has been specified and there were any

•

missing DLLs.

If the linker is building a program that has a user library and the linker has not been

•

able to open the user library.

The linker does not check for unresolved references when the -r option is specified,
and eld reports an error if you specify any of the options described above with -r.

Note that, even if the linker is not presetting, it will still try to resolve references for the
purpose of producing messages about unresolved symbols.

If there are unresolved references to symbols that are not globalized, and this is not
being considered an error, and the linker is presetting, then the linker must decide what
to do with those references. If the reference is to a symbol that is expected to be code,
the linker will look for a symbol named UNRESOLVED_PROCEDURE_CALLED_. The
linker looks for this symbol by first looking for a symbol of this name that is exported by
the loadfile being created, and then looks for the symbol in the usual way through
DLLs. If found, and it is a procedure, then the references to the desired symbol are
resolved to this symbol, and the file can still be preset. The references are still
considered to be unresolved as far as putting out messages about unresolved symbols
is concerned. If presetting is successful in this case, the LIC tells that there were
unresolved references.

Handling Unresolved References

If unresolved references to symbols that are not globalized cannot be handled as
described in the previous paragraph then the linker decides that the file cannot be
preset. Therefore, whenever a file is preset, it means that all references to symbols
that are not globalized were resolved to something.

The reason that unresolved references to code get more lenient treatment than
unresolved references to data is that it is possible to handle them in a more predictable
way at runtime. Specifically, the HP NonStop operating system provides an
implementation of UNRESOLVED_PROCEDURE_CALLED_ that generates a SIGILL
signal that can be caught but not deferred.

Whether or not the linker can preset is not affected by whether there are any
unresolved references to globalized symbols.
UNRESOLVED_PROCEDURE_CALLED_ is never used to handle unresolved references
to globalized symbols. UNRESOLVED_PROCEDURE_CALLED_ is also not used to
handle unresolved references to $n_EnterPrivN symbols from gateways.

There is also an option named -set rld_unresolved, with the same three
parameter values as for -unres_symbols, and with error as the default. The linker
places the value specified by this option into the RUNTIME_UNRES_CHECKING bits of

eld Manual—527255-009

3-9

Binding of References

the flags field of the .tandem_info section. This tells rld how it should treat
unresolved references at runtime. Even if this loadfile is preset, and even if rld can
verify that the presetting is correct, rld will still repeat the presetting process in order

to generate the error or warning messages requested by the
RUNTIME_UNRES_CHECKING bits if the LIC says that there were unresolved
references.

The bits set by -set rld_unresolved also provide defaults for how -alf treats
unresolved references.

There is no option for specifying the treatment of unresolved references based on a
symbol’s name.

Using User Libraries

A user library is a DLL that is found in a special way by a program.
The -set libname option, given to the linker when it is building a program, tells the

filename for the user library as it needs to be present at runtime. eld reports an error if
you give this option when not building a program. The -set option is described The -

set and -change Options on page 4-8.

Using User Libraries

The option -libname may be used as a synonym for -set libname. The specified
user library name must always have the form $a.b.c, i.e., a valid Guardian file name,
fully qualified up to the volume name, and not including the system name, because this
is the only type of name that will work at runtime. Note that, when running the linker on
OSS, one would need to do something such as putting the name in single quotation
marks or preceding it with a backslash to avoid the special meaning of the dollar sign
to the shell. The linker places the name specified by the -set libnamee option into
the .tandem_info section of the program that it is creating. The linker also converts the
name to upper case, if not done already. On Guardian APIs, single quotes do not work
because they are not recognized by the HP Tandem Advanced Command Language
(TACL); therefore, it is not important to specify them.

The -local_libname option tells the linker the filename of the user library to use at
link time. Section 3, Binding of References explains how this user library is used,
similarly to other DLLs, when the linker is fixing up references. It is not an error if the
linker can’t find the user library, but it does mean that the linker cannot preset the
program that it is creating.

The locations of the -set libname and -local_libname options in the command
stream are irrelevant. These options may only be used when building a program.
Additional rules related to these options depend on the platform:

The PC hosted linker knows that it is building a program that uses a user library
because the -set libname option is used. If the -local_libname option is not
used then the linker can’t find the user library. eld reports an error if you specify ­local_libname without -set libname.

eld Manual—527255-009

3-10

Binding of References

On Guardian, the linker knows that it is building a program that uses a user library
because either -set libname or -local_libname is given. If only one of these is
given, it provides a default for the other one. Specifically, if -local_libname is not
given, the linker uses the parameter of -set libname for the value of ­local_libname. Or, if -set libname is not given, the linker uses the name
specified for -local_libname, but fully qualifying it by adding the volume and
subvolume name if necessary, and omitting the system name. The volume and
subvolume names used are the defaults that this instance of the linker would use for
opening files with partially qualified names.

The rules on OSS are similar to those of Guardian. If -local_libname is not given,
the linker converts the name specified in -set libname to the form /G/a/b/c for use
at link time (not converting it to upper case). Conversely, if -set libname is not
given, the linker requires that the name specified for -local_libname be located in
the Guardian name space, and then the fully qualified Guardian name of the file, not
including the system name, is used for -set libname.

The linker is not required to open the -local_libname file unless it is either
presetting the main program or checking for unresolved references. If it can’t open the
file, that is handled the same way as if -allow_missing_libs was specified and
the linker couldn’t find a DLL, including the production of a warning message.

Creating Import Libraries

Creating Import Libraries

There are three kinds of import libraries:

A complete import library may represent a single DLL, providing the linker all the same
information at link time as if the DLL itself were present.

An incomplete import library similarly represents a DLL but with only some of the
information that the linker needs at link time.

A special import library with the DLL name “__IMPLICIT_LIB__” represents the entire
set of implicit libraries.

The linker can create an import library at the same time that it is creating the
corresponding DLL, and it can also create an import library from one or more DLLs that
already exist.

Whenever an import library is created, by default, it is a complete import library. If the

-set incomplete on option is provided then the import library is incomplete. This

doesn’t necessarily change what is in the import library; it just marks it incomplete to
indicate that the symbolic addresses within it are not to be considered reliable. The
import library that represents the implicit libraries must always be complete (so it is an
error to specify -set incomplete on in that case).

In all cases, the linker creates the import library file by following the same rules as
given earlier in The Creation of Output Object Files

of the work file is ZLDAInnn rather than ZLDAFnnn, the name of the intermediate file, if
desired, is specified by the -temp_i option rather than the -temp_o option, and

on page 2-5, except that the name

eld Manual—527255-009

3-11

Binding of References

Creating an Import Library at the Same Time That a

DLL is Created

there similarly is a -must_use_iname option instead of -must_use_oname. An
existing file of the same name is not replaced if the linker terminates with any errors.

The -change incomplete on option can be used to demote an import library from
complete to incomplete. It is not possible to demote the import library that represents
the implicit libraries. It is not possible to “un-demote” an incomplete import library so
that it becomes a complete import library.

The following subsections also tell how the linker decides whether to include DWARF
symbol table information in an import library when it creates it. As described in

Updating Or Stripping DWARF Symbol Table Information on page 4-14, the -strip

option may be used to remove DWARF symbol table information from an existing
loadfile or import library.

Creating an Import Library at the Same Time That a DLL is
Created

The following option:

-import_lib <filename>

tells the linker to create an import library at the same time that it creates the
corresponding DLL. If you use this option, and the DLL has DWARF symbols
information, then so will the import library. If the DLL is being created without DWARF
symbols information, through the use of the -s or -x options, then the import library
will also not have DWARF symbols information.

The following option:

-import_lib_stripped <filename>

similarly tells the linker to create an import library, but in this case the import library
does not contain DWARF symbol table information, even if the DLL does.

Creating Import Libraries From Existing DLLs

The following option:

-make_import_lib <filename>

tells the linker to make an import library out of one or more existing DLLs. The other
filenames in the command stream are the DLLs that the import library will represent.

eld reports an error if you specify -make_import_lib without specifying any DLLs

in the command stream.
If all the DLLs have the EF_TANDEM_IMPLICIT_LIB bit set in their ELF headers, the

linker creates the import library that represents the implicit libraries. In this case, the
EF_TANDEM_IMPLICIT_LIB bit is set in the import library that the linker is creating, it
is given the DLL name “__IMPLICIT_LIB__”, and
overlap among the names of the symbols exported by the various input DLLs, unless
all the copies of the symbol have the STO_MULTIPLE_DEF_OK bit set. It is also an
error if any of the implicit DLL's is not preset. If any of the implicit DLL's is preset, but

eld reports an error if there is any

eld Manual—527255-009

3-12

Binding of References

has unresolved references, that is either an error, warning, or ignored, depending on
what is specified for the -unres_symbols option, similar to how this option is used
when building a new loadfile. If the -unres_symbols option was not specified, the
default in this situation is error. The import library that represents the implicit DLL's
never has DWARF symbol table information.

The address of the import library that represents the implicit DLL's is specified the
same way as for the text segment of a DLL. In particular, this includes the use of a
DLL registry. The name of the entry to use in the registry file would be the same as the
filename specified in the -make_import_lib option.

Otherwise, not all the DLL's on the command line have the
EF_TANDEM_IMPLICIT_LIB bit set in their ELF headers. In this case, it is required
that there be only one DLL in the command stream, and the import library will
represent it with the same DLL name. By default, the import library created will have
the same DWARF symbols information as the existing DLL. However, if either the -s
or -x option is given, the import library will not contain DWARF symbols information.

The following are the options allowed when creating an import library that represents a
single DLL:

Creating Import Libraries From Existing DLLs

-must_use_iname

-no_banner

-no_verbose

-NS_extent_size

-NS_max_extents

-obey

-s

-set incomplete on

-stdin

-temp_i

-verbose

-vslisting

-warn

-x

The following are the options allowed when creating the import library that represents
the implicit DLL's:

-check_registry

-must_use_iname

-must_use_rname

-no_banner

-no_verbose

-NS_extent_size

-NS_max_extents

-obey

-stdin

-t

eld Manual—527255-009

3-13

Binding of References

-temp_i

-temp_r

-unres_symbols

-update_registry

-verbose

-vslising

-warn

Ignoring Optional Libraries

This section decribes the feature whereby eld can be told to omit certain DLL's from
the liblist if they appear to be unnecessary. Note that eld always does this processing,
regardless of whether it is presetting the file. eld does not fix up references to
globalized symbols found in other DLL's, since the fixups would always need to be
updated by rld anyway, but eld still looks up globalized symbols in DLL's in order to
see if some DLL would resolve a reference to an undefined globalized symbol, for the
purpose of deciding which DLL's are optional.

Ignoring Optional Libraries

For every indirectly found DLL in the search list, there was one other DLL that was
already in the search list and that caused this DLL to be added to the search list. If
that other DLL was also an indirect DLL, then it similarly was pointed at by something
else, etc. In this way, every indirectly found DLL can trace its presence in the search
list back to one DLL that was explicitly given in the command stream, or to the user
library. The set of all the DLL's that trace their presence back in this way to a given
DLL A is called the search list addition set of A.

If a DLL that was named explicitly in the command stream was not actually used to
resolve any references, and furthermore none of the DLL's in its search list addition set
were used to resolve any references, then that DLL is called unnecessary, because the
presence of that DLL in the command stream did not affect how the linker preset the
file. For example, if that DLL had not been specified in the command stream, then it or
the other DLL's in its search list addition set might instead have been found some other
way, but in all cases they would have to come later in the search list then they actually
did, or be absent entirely. That means that they wouldn't have had any consequences
that they didn't have in the actual link: they wouldn't have resolved any references, and
they wouldn't have caused other DLL's to be added to the search list. The resulting
search list would still have been the same, at least with regard to the presence of the
DLL's that were used to resolve references, and to the ordering of those DLL's among
themselves.

The options named -optional_lib and -no_optional_lib are command stream
toggles that determine whether the linker considers a DLL that is specified in the
command stream to be optional. These options can be specified multiple times in the
command stream, each time setting the mode for subsequent DLL's in the command
stream until the mode is changed again. At the beginning of the command stream the
mode is -no_optional_lib. If an optional DLL turns out to be unnecessary, then
the linker will assume it is okay to ignore that DLL, and it will not be listed in the .liblist
section. If eld is presetting, and therefore creating a LIC, then the LIC is created as if

eld Manual—527255-009

3-14

Binding of References

the omitted .liblist entries had never been present. For example, some of the DLL's in
the search list addition set of such a .liblist entry may still be present in the LIC, and
some not, and if present their positions in the LIC may change, depending on other
ways of getting to those DLL's indirectly.

When some elements of the .liblist section have been omitted, with corresponding
changes to the LIC if present, we say that the .liblist and LIC have been abbreviated.

Note that eld always does this -optional_lib processing. It doesn't depend, for
example, on whether eld is presetting the loadfile.

If all the same direct and indirect DLL's as were found by the linker would also have
been found at runtime regardless of whether the .liblist was abbreviated, as described
above, and all these DLL's would have been found in the same order and with the
same export digests, then the linker's presetting would give the same results as what
would happen at runtime with no such abbreviation. In this case, the -optional_lib
option is just an optimization, preventing some DLL's from being loaded into a process
when those DLL's would not have affected how the loadfile would be fixed up when it
was loaded into memory. The abbreviated LIC, if present, corresponding to the
abbreviated .liblist, will similarly lead to the conclusion that the linker fixed up all the
reference sites correctly, so the file can run without being rebound at load time (except,
of course, that references to globalized symbols always need to be rebound).

Ignoring Optional Libraries

In other cases, the use of the -optional_lib option is not just an optimization, but
rather can cause the loadfile to run differently. These are the cases where the DLL's
that were omitted from the abbreviated .liblist or abbreviated LIC would have been
found at runtime, and would have had different export digests from the ones that the
linker saw, or would have been found in a different order, or would have indirectly
brought in other DLL's that the linker didn't see. In such cases, the abbreviated .liblist
and abbreviated LIC might lead to the conclusion that the file was fixed up correctly by
the linker, and allowed to run without being rebound, even though if it were rebound at
load time based on a .liblist that had not been abbreviated then some of the bindings
might have been different. Or, if the abbreviated .liblist and abbreviated LIC don't lead
to the conclusion that the file had been correctly fixed up by the linker, the file is
rebound at load time, but the use of the abbreviated .liblist could still lead to different
bindings from what would have occurred with a .liblist that was not abbreviated.

The use of the -optional_lib option can also affect how things are fixed up at load
time with regard to globalized symbols, because eld does not take globalized symbols
into account when it decides which DLL's are unnecessary.

Also, even if the abbreviated .liblist and LIC don't affect how the loadfile itself is fixed
up at load time, the abbreviations will result in different DLL's being present in memory,
or being loaded in a different order, in a way that could cause the dlsym runtime routine
to give different results.

In any case, the use of the -optional_lib option can affect a program's semantics,
so it should not be used unless the consequences are understood.

A special case is when eld finds a DLL on the command line that is the same file as
what was specified for the user library. In such a case, an entry is still made in the

eld Manual—527255-009

3-15

Binding of References

.liblist section for such a DLL. With regard to the -optional_lib option, this option
ever causes such an entry to be removed from the .liblist. The point is that such an
entry is only significant if a different user library were to be used at runtime, and eld
does not try to analyze whether this .liblist entry would be "necessary" if a different
user library had been present.

The main intended use of these options is for -optional_lib to be placed before
the set of DLL names that a compiler may automatically place at the end of the
command stream that it sends to the linker, for a set of DLL's that it thinks the user
might generally need. Such DLL's would often be unnecessary, depending on which
language features the program used. Since these DLL's are at the end of the
command stream, they would come after all other DLL's in resolving references,
except for the implicit DLL's. Therefore, this use of -optional_lib would have no
runtime consequences, unless the user wanted to be able to get a different version of
one of these libraries at runtime, with additional symbols in it that hid symbols
otherwise found in the implicit libraries.

Note that this is not necessarily the most general way to define "unnecessary", nor is
there necessarily any one best way to do it. For example, suppose that DLL's A and B
both point at C, and C is used to resolve references, but neither A nor B themselves
resolve any references. You could argue that either A or B could be considered
unnecessary on its own, but you can't say that they are both unnecessary at the same
time without figuring out how you are going to get to C. The definition of "unnecessary"
given in this section can be applied separately to each DLL in the command stream,
without having to take into account such dependencies. As it actually would work in
this case, the linker could only ignore A or B if it was not the one that led to putting C
into the search list. For instance, suppose A came before B in the .liblist section of the
program, so that A caused C to be in the search list. Then, the linker would ignore B if
the user marked B optional, but there would be no way to tell the linker to ignore A (i.e.,
without changing other things in the linker's command stream, such as the ordering of
A and B ).

Merging Symbols Found in Input Linkfiles

Merging Symbols Found in Input Linkfiles

TNS/E linkfiles contain ELF symbol tables. The linker merges the symbol information
from the input files into its output file, creating an ELF symbol table if the output file is a

linkfile, or creating the .dynsym and .dynsym.gblzd sections if the output file is a

loadfile.

In loadfiles, globalized symbols are placed into the .dynsym.gblzd section, while all
other symbols are placed into the .dynsym section.

If the -make_implicit_lib option is given then eld reports an error if you have any
globalized symbols. Also, if the -instance_data option is specified with a
parameter value of data2protected or data2hidden then eld reports an error if
you have any globalized symbols.

Note. The data2protected parameter is supported on systems running J06.09 or
earlier J-series RVUs and H06.20 or earlier H-series RVUs.

eld Manual—527255-009

3-16

Binding of References

In linkfiles, entries in the ELF symbol table tell the source language for each symbol.

When there are multiple entries of the same name that have been defined and
allocated by the compiler or assembler, the rules followed by the linker in deciding
which copy to keep are found inAccepting Multiply-Defined Symbols on page 3-17.

If there is only one entry that has been defined and allocated by the compiler or
assembler, the linker keeps that one. If there are no such entries, but there is an entry
for the symbol as common data, the linker will choose such an entry and allocate the

symbol in the .bss section. If there are multiple common data entries for a symbol, the

linker chooses the first one among those with the largest size. Otherwise all the
entries are just external references, and the symbol remains an external reference in
the output file, with the linker keeping the first one it sees.

The -y option tells the linker to print out information about a symbol of a given name,
telling the names of the linkfiles that mentioned the symbol in their ELF symbol tables
and giving the information provided about the symbol in each of those files.

Object files also contain DWARF symbol table information for the use of debuggers.
See Updating Or Stripping DWARF Symbol Table Information on page 4-14.

Accepting Multiply-Defined Symbols

Accepting Multiply-Defined Symbols

This section is only concerned with symbols that are defined and allocated by the
compiler or assembler, not with symbols that are external references or common data.
This section covers global definitions, which make it possible to have multiple
definitions of the same symbol. Multiple definitions are only allowed if all the definitions
are as data items, or if all the definitions are as procedures, with different rules for the
two cases as described below.

Rules For Data Items

Here are the rules concerning multiple definitions of a data item:

A symbol of a given name that occurs in one the sections named .data, .sdata,

•

.bss, and .sbss, is allowed to come up in different sections among these four

possibilities in different linkfiles. Similarly, a symbol of a given name that occurs

in one of the sections named .rdata and .srdata is allowed to come up in

different setions among these two possibilities in different linkfiles. A symbol
that occurs in any other data section must only occur in that same named data
section in all the linker’s input linkfiles.

eld reports an error if an initialized data item (including "zero-initialized" data

•

items found in the .bss or .sbss sections, which in the case of C++ also
includes data that was not explicitly initialized in the source) is defined in more

than one C or C++ file unless the STO_MULTIPLE_DEF_OK bit is set in all the

corresponding ELF symbol table entries. HP’s definitions of C and C++ say
that it is an error for users to create such situations, but the

STO_MULTIPLE_DEF_OK bit allows the compiler to do it.

eld Manual—527255-009

3-17

Binding of References

The linker uses the st_size field in the ELF symbol tables of its input files to

•

understand the sizes of data items. When there are multiple definitions of a
data item eld reports an error if the sizes are not the same.

It is not an error if some of the definitions have initial values (i.e., in the .data or
.sdata sections) and others don’t (i.e., in the .bss or .sbss sections). However,
eld reports an error if the initial values are not the same in all the copies of the

data that are initialized. Data in the .bss and .sbss sections is considered to
have the initial value zero.

When there are multiple definitions of a data item, and it is not an error, the linker must
choose which copy to use. The linker makes this choice by comparing copies in the
following ways:

Choose an instance that is initialized over one that isn’t (i.e., choose .data or

•

.sdata over .bss or .sbss).

If that doesn’t narrow it down to one choice, choose an instance whose

•

language is C or C++ over one that isn’t. Doing this, after the previous rule, is
convenient for enforcing the rules given above about initialized definitions in C
and C++.

Rules for Procedures

If that doesn’t narrow it down to one choice, choose the first instance

•

encountered.

Note that the linker does not care whether various definitions are short data (namely,

the .sdata, .srdata, and .sbss sections) versus long data (namely, the .data,
.rdata, and .bss sections). If the above rules cause the linker to choose a copy of a

symbol that cannot be reached by 22-bit GP-relative addressing, and 22-bit GP­relative addressing is used for the symbol, it is an error.

Rules for Procedures

Here are the rules concerning multiple definitions of a procedure:

It is an error unless either the STO_MULTIPLE_DEF_OK bit is set in all the

•

corresponding ELF symbol table entries, or the -allow_duplicate_procs option
is used.

It is an error if any copy of the procedure has the CALLABLE or

•

KERNEL_CALLABLE attribute.

It is an error if the various copies do not all agree on the MAIN, SHELL,

•

EXTENSIBLE, and COMPILED_NONSTOP attributes.

There is no requirement that multiple definitions of the same procedure contain the
same code or have the same size.

When there are multiple definitions of a procedure, and it is not an error, the linker
must choose which copy to use.

eld Manual—527255-009

3-18

Binding of References

If two copies of the procedure agree on the RESIDENT attributes, the linker prefers the

first one it sees.

The linker prefers one that is RESIDENT over one that is not RESIDENT. Note that the
linker doesn’t know why someone thought the procedure needed to be RESIDENT, but

as long as at least one copy said so, the linker assumes it is necessary.

In all cases, after the linker chooses which copy to use, that determines the contents of
the code for the procedure.

The above rules about duplicate symbols apply both when the linker is creating a
loadfile as well as when the linker is creating a linkfile with the -r option.

When there are multiple definitions of a symbol, the one chosen by the linker is the
only one still represented in the ELF symbol table of the output file (if it is a linkfile), or

in the .dynsym or .dynsym.gblzd section of the output file (if it is a loadfile).

All references to a symbol of this name get fixed up to this copy of the symbol.

Note that the linker never uses DWARF information to decide if multiple definitions are
allowed, or to decide which definition to keep. (The linker never uses DWARF
information to decide things outside of DWARF itself, because the DWARF information
can be stripped from linkfiles.) When the linker fills in addresses of symbols in the
DWARF information, it fills in -1 for the address of an unused copy of a symbol. The
linker does this for both linkfiles and loadfiles.

Using the -cross_dll_cleanup option

The information about unused copies of procedures is deleted from the .procinfo

section of a linkfile, and from the stack unwinding information of a linkfile or loadfile.

The -show_multiple_defs option tells the linker to print out information about global
symbols that are multiply defined. The result is similar to giving a -y option about each

such symbol, except that it isn’t necessary to know ahead of time which symbols they
are, and the information only comes out about the linkfiles that defined the symbol, not
about other linkfiles that only mentioned it as an external reference.

Using the -cross_dll_cleanup option

The -cross_dll_cleanup option is used to reduce the total size of a program and
the private DLLs that are used by a process. This option affects the behavior of the
eld program with regard to symbols eld finds in its input linkfiles that have all the
following properties:

The symbol is a global symbol.

•

The symbol is a definition (not an external reference).

•

The symbol is a procedure.

•

The symbol is marked STO_MULTIPLE_DEF_OK (implying that it is a multidef or

•

globalized symbol).

Without the -cross_dll_cleanup option, you can store multiple copies of a symbol
that have the above properties, and eld discards the code for all except one copy of

eld Manual—527255-009

3-19

Binding of References

the symbol. When the -cross_dll_cleanup option is specified, eld also verifies if a
symbol of the same name is found in a DLL. If it finds a same name, eld deems the
last copy of the procedure as "unused", and its code can be cleaned up. The
references to the symbol are therefore resolved to the copy of the symbol in the DLL.

When the -cross_dll_cleanup option is used, it is necessary that all the input
linkfiles be compiled with the -Wglobalized option (the same as when eld is
specified to build a globalized DLL, since this new option is a form of preemption).

To get maximum benefit from the -cross_dll_cleanup option, list the DLLs that are
directly used (on the eld command line), and also DLLs that previously were only
indirectly used.

Specifying Which Symbols to Export, and Creating

the Export Digest

Specifying Which Symbols to Export, and
Creating the Export Digest

When creating a loadfile the linker must determine which symbols to export. If no
options related to this are given in the linker’s command stream then its default

behavior is that it exports a symbol if it is a global symbol and the STO_EXPORT bit is

set in some ELF symbol table entry for the symbol in the linker’s input files. This is the
way the compiler or assembler tells the linker that certain symbols should be exported.

If the STO_EXPORT bit is set in any ELF symbol table entry for a symbol in the linker’s

input linkfiles, and the linker is creating a linkfile, then this bit is set in the linker’s output
file.

If the -export_all option is used then the linker exports all defined, global symbols

except for those in the following categories:

Procedures whose names begin with the special prefixes that mark them for

•

inclusion in the ctors, dtors, initz, or termz arrays.

Symbols that are specially known to the linker and have names that are

•

intended to only be meaningful within the loadfile being created. This includes
all the predefined symbols created by the linker, such as the symbols that are

the names of the ctors, dtors, initz, and termz arrays. However, -export_all
does cause _MCB to be exported, if the linker has created that symbol.

The above rules can be overridden for specific symbols by name. If the ­exported_symbol option is specified then the symbol of the specified name is
unconditionally exported. If the -hidden_symbol option is specified then the symbol of
the specified name is unconditionally not exported. It is an error if the same symbol is
specified in both of these options. It is an error if the symbol specified in the

-exported_symbol option is not a global symbol that is defined in the loadfile being
created. It is a warning rather than an error if such a symbol is specified in the ­hidden_symbol option.

Note that globalized symbols are not treated specially with regard to these rules. That
means they are exported by default because they have the STO_EXPORT bit set, but

you can avoid exporting them by using the -hidden_symbol option.

eld Manual—527255-009

3-20

Binding of References

The option -export is accepted as a synonym for -exported_symbol, and -export_not as
a synonym for -hidden_symbol.

Exported symbols are identified in the .dynsym and .dynsym.gblzd sections by the fact
that they are marked STB_GLOBAL and not SHN_UNDEF. If a symbol that was

STB_GLOBAL in its input linkfile is not exported, that fact is indicated by marking it as
STB_LOCAL rather than STB_GLOBAL in the output loadfile.

The linker calculates the export digest based on the names and addresses of exported

symbols in the .dynsym section, and on the GP value for the loadfile, and stores it in
the export_digest field of the .tandem_info section. Globalized symbols are not

included in the calculation of the export digest.

The options described in this section are not allowed if -r is specified.

If you are starting with code that had been a single program before, perhaps built from
archives, and now you are changing it to be split up among several DLLs, you might

find it useful to build the program and DLLs with the -b globalized and -export_all

options, to assure that all symbolic references among the program and DLLs keep
referring to a single copy of each symbol.

Processing of Code and Data Sections

Processing of Code and Data Sections

A text section contains procedures. A data section contains data that is allocated at a

certain address in virtual memory when the loadfile is brought into memory, as
opposed to data that is dynamically allocated on the stack or in the heap.

The linker checks that the sizes of all code and data sections are multiples of 16 bytes.

Concatenating Code and Data Sections Found in the Input
Linkfiles

A linkfile may have many text sections, with names beginning either .text or .restext.
When the linker is creating a new linkfile with the -r option, it concatenates text

sections of the same names in its input files to create text sections of those same
names in its output file. When section names are the same in different input linkfiles,
the linker concatenates them in the same order as the linker saw those linkfiles.

However, when the linker creates a loadfile, it combines all the input sections whose

names begin .text into a single output text section named .text, and similarly for
.restext. No guarantee is given as to the order in which different text sections whose
names begin .text are combined into a single text section named .text, and similarly for
.restext.

With regard to data sections, again, the linker usually concatenates data sections of
the same names in its input files into data sections of the same names in its output file,
and the linker does this whether creating a linkfile or a loadfile. Except, when an input

linkfile has a section named .rdata, and it contains no relocation sites, the linker
changes the name of that input section to .rconst, and combines all sections named
.rconst into a section of that name in its output file accordingly.

eld Manual—527255-009

3-21

Binding of References

When creating a linkfile, the linker similarly concatenates the relocation tables that
accompany the code and data sections.

The linker’s input linkfiles may also contain common data. Such data items are defined,

but not assigned addresses within sections. If a normal definition of the same symbol is
found, the common data definitions are ignored. If there is no normal definition, and the
linker is creating a loadfile, the linker converts the common data symbol into a data

symbol that is allocated space in the .bss section. Common data cannot have initial

values.

If you are creating an implicit DLL (with the -make_implicit_lib option) eld reports an
error if you have any data that would need to go into the data variable segment (i.e., ­instance_data data1constant is imposed).

Public Libraries and DLLs

TNS/E supports public libraries. Public libraries are a set of (DLL) libraries, available to
all users of the system, and managed as part of the system software. They are mostly
supplied by HP, although you and third party software providers can also provide DLLs
to be added to the public DLLs. You use DSM/SCM to add your DLLs to the public
libraries. Note that these must be loadfiles, not linkfiles.

Public Libraries and DLLs

Public libraries include:

TNS/E compiler run-time libraries.

•

Libraries that support connections to TNS/E communication facilities.

•

Certain TNS/E tools, utilities, and the loader library (rld).

•

TNS/E compilers generate needed linkages from PIC programs and DLLs to the
compilers’ run-time libraries.

In addition to accessing public libraries, PIC programs and DLLs will automatically
access the system and millicode libraries, without your specifying this linkage
requirement. The system and millicode libraries are PIC libraries that the system loads
before loading any application code, and the loader and operating system
automatically link your application to these libraries as appropriate. These are known
as implicit libraries because every loadfile is implicitly a user of them.

This can be contrasted with the public DLLs, which are explicit because a loadfile must
explicitly ask to use a public DLL, although you need not specify where to find the
public DLL. The combination of the ZREG file (the Public LIbrary Registry file) and
ZREGPTR (pointer) file specifies the location.

One main user of the ZREG file (and the ZREGPTR) is the preloader. Public DLLs are
preloaded during coldload, reload of a CPU or when a set of public DLLs is replaced
online. The other main user is the linker (
finding the ZREG file that is in the same subdirectory, then searches the registry. The
linker does not use the ZREGPTR pointer directly, but acquires its information from the
preloader by use of a procedure call.

eld). Typically, eld “finds” the DLLs by

eld Manual—527255-009

3-22

Binding of References

Each set of public libraries is installed in a separate subvolume, separate from the
SYSnn subvolume and separate from any other set of public DLLs. This subvolume is
on the same disk as the SYSnn subvolume.

The SYSnn subvolume also contains the imp-imp file, named zimpimp. This is the
import file usable for resolving external references to the explicit libraries. The imp-imp
file can be copied to the public-DLL subvolume. This renders the public-DLL
subvolume portable. A portable public-DLL subvolume contains everything the linker
needs to link files to use these particular public libraries. A portable subvolume can be
copied for use by the linker (eld) on another system or another platform, such as a PC.

The Public Library Registry

The public-DLL registry file (ZREG) serves as an interface between DSM/SCM (that
you use), the public-library installation tool (that HP uses), the preloader and the linker.

DSM/SCM creates an initial registry file, listing all the public DLLs by name. This is an
edit file (filecode 101). Use DSM/SCM to add your public DLLs to those provided by
HP.

The Public Library Registry

Entries to the file consist of a series of statements. The dll statement describes a public
DLL. In its simplest form, it is just a name, for example:

dll file ztestdll;

Here is another example; it contains the license attribute. A licensed DLL is one that
contains priviliged code. Unless you use this attribute along with the value “1”, the
default is “0”, which means the DLL is unlicensed.

dll license 1, file privdll;

There are other attributes which are created automatically, for example the timestamps
that you and the tools can use for version control. Here are two examples, the
link_timestamp (from when the linker first created the DLL), and the update_timestamp
(from when the linker last updated the DLL, or when another tool rebases or presets it):

dll file zredll,
link_timestamp 2004-08-01 16:34:41.213592,
update_timestamp 2004-08-01 17:15:17.119634;

From these examples you can see that attributes can be in any order, attributes are
separated by commas, and statements are terminated by semicolons.

Finding and Reading The Public DLL Registry (ZREG) File

The linker always tries to find the public DLL registry file whenever it is creating a
loadfile. There are three ways that the linker may find the public DLL registry file:

1. If the -public_registry option is specified, that tells the name of the public DLL

registry file. (This option could also be used to override another location of the zreg
file.) If the file does not exist, or the linker cannot open the specified file for
reading, eld reports an error.

eld Manual—527255-009

3-23

Binding of References

2. If the -public_registry option is not specified then the linker looks for a file named

zreg in its own directory or subvolume. If this location is a \bin or /bin, eld will also

look in a corresponding \lib or /lib location. This supports the practice, on PCs and
OSS, of putting eld in a bin directory and the public DLLs (together with the zreg
file) in a sibling lib directory.

On OSS, where case is significant, zreg is lower case. If the file exists and the

linker can open it for reading, this file is deemed to be the public registry file.

Otherwise, if the -nostdlib option has not been specified, the linker writes out a

warning message.

3. If still not found, and the host platform is TNS/E, the linker uses a system call

(pubLibSpecs_get_) to find the location of the zreg file.

If the linker finds the public DLL registry, it then determines a list of public DLL
filenames. This information is used elsewhere in the linker for two purposes.

First, it is used to locate public DLLs, as discussed in Finding Public DLLs on
page 2-18. Second, it is used to locate the import library that represents the implicit
libraries, as discussed in Presetting Loadfiles on page 3-5.

Finding and Reading The Public DLL Registry

(ZREG) File

As explained in those two sections, a filename found within the public DLL registry file
may be used by the linker to search for a file on a platform where filenames are case
sensitive. In that case, the linker will interpret what it finds within the public DLL registry
to be lower case. So, to avoid confusion, it is strongly recommended that all filenames
mentioned in the public DLL registry be written in lower case, and that when
corresponding files exist on a platform where case is significant those files are given
lower case filenames, and furthermore that the DLL names found within such files are
also written in lower case.

eld Manual—527255-009

3-24

4 Other eld Processing

This section contains the following information:

Adjusting Loadfiles: The -alf Option - how to repeat the presetting of a loadfile when

DLLs change.

The -set and -change Options - how to set various options within the loadfile.

eld Functionality for 64-Bit - how the linker performs consistency checks.

Renaming Symbols - how the linker treats each input file.

Updating Or Stripping DWARF Symbol Table Information - from the input and output

object files.

Modifying the Data Sections that Contain Stack Unwinding Information - when

concatenating sections to create a new loadfile.

Creating the MCB - the Master Control Block contains key settings such as product

version numbers, valid file types, language dialects, and so on.

Processing of Floating Point Versions and Data Models - more consistency checks.

Specification of the Main Entry Point - there are two ways to specify the main entry

point.

Specifying Runtime Search Path Information for DLLs - eld tells rld where to find the

DLLs.

Merging Source RTDUs - used with SQL/MP.

Adjusting Loadfiles: The -alf Option

The main purpose of this option is to tell the linker to repeat the process of presetting
an existing loadfile. Most likely, this is done because some of the DLLs used by this
loadfile have changed, and therefore resolving the references against the newer set of
DLLs will allow the loadfile to load more quickly. The updating of the loadfile might
happen automatically at runtime, but this option provides a way of making sure the file
is updated by user request. It would also be possible to relink the file from its
constituent pieces, but -alf makes it possible to update the references even if those
pieces are no longer present and without knowing everything about how the original
link was done.

It is also possible that the loadfile had not been preset before, in which case this option
would be presetting it for the first time.

It is also possible to rebase a DLL while rebinding it. And, when a DLL is rebased by

-alf, it is also possible for the text and data segments to be rebased by different
amounts. If there are two data segments, they are always rebased by the same
amount. The gateway segment of a DLL is rebased together with the data segment.

-alf stands for “Adjust LoadFile”.

eld Manual—527255-009

4-1

Other eld Processing

-alf recreates the file by the usual linker mechanisms.

Certain relocation sites within a file must be set up by the linker, whether the file is
preset or not, and must never become inconsistent thereafter. That is because
rebinding makes use of the existing values at those sites. Such sites only need
modification if a file is being rebased. Because updating in place would run the risk of
terminating unexpectedly in the middle, leaving such sites inconsistent, we never
update in place when rebasing is being done. This is why -alf always recreates the
file, rather than updating it in place.

The -alf option can be applied to a DLL whose segments are not contiguous, i.e.,
when the DLL was created by using the -d option to place its data separate from its
code.

The parameter to the -alf option is the name of an existing program or DLL. eld
reports an error if this file does not exist, or if it is any other kind of file. This option
performs the same version number checking on this loadfile as is described in Input

Object Files on page 2-12.

When the -alf option is used, the names of input linkfiles cannot be specified. All the
code, data, symbols information, etc., comes from the existing loadfile. Archives and
DLLs cannot be specified, either directly in the command stream or with -l options.
The linker uses the DLL names found in the .liblist section of the existing loadfile as if
they were specified in the command stream with -l options.

Adjusting Loadfiles: The -alf Option

When the -alf option is used, it is possible to put the name of the import library that
represents the implicit libraries directly on the command line. This is an exception to
the rule stated in the previous paragraph, that no filenames can be on the command
line. On the other hand, it keeps the processing of the -alf option consistent with
usual linker processing with regard to the ability to get the name of this import library
from the command line. The filename specified on the command line overrides any
other way the -alf option may have found the import library that represents the
implicit libraries.

eld reports an error if you have more than one filename on the

command line with -alf . The -alf option always reset the goldsmith_region_info
and goldsmith_region_addr fields of the .tandem_info section to zero.

The -alf option updates the update_timestamp if there were any other changes
made to the file. It does not update the update_timestamp if that would be the only
change to the file. It never updates the creation_timestamp. An informational message
tells whether the file required any changes.

The -alf option cannot create an import library in parallel with updating a loadfile, nor
can they be used to update an import library. When the -alf option is used to rebase
a DLL, many things in the DLL change in ways that affect users of that DLL, such as
the addresses of its exported symbols. If you had an import library that matched the
previous version of that DLL, you would therefore probably want to run the linker with
the -make_import_lib command on the new DLL afterward in order to create a
new import library that matched it. Do not worry about this when using the

-alf option just to rebind a DLL, because in that case the only change to the DLL
that would be reflected in a corresponding import library is whether the ELF file header

eld Manual—527255-009

4-2

Other eld Processing

said that the DLL was preset, and that bit isn’t really of any importance in an import
library.

The following are some things that cannot be specified with this option because they
are unconditionally inherited from the existing version of the loadfile:

It is not possible to specify import controls.

•

It is not possible to say which symbols are exported.

•

If it is a DLL, it is not possible to say what its DLL name is.

•

Only one -alf option can be specified in the linker command stream.
Additional rules about the -alf option is given in the following subsection.

Additional rules about -alf

In addition to updating the references within an existing DLL or program to other DLLs,
the -alf option may be used to rebase an existing DLL. It is not possible to rebase a
program.

Additional rules about -alf

To rebase a DLL with -alf, specify the -t option to tell the new starting address for
the text segment. The data segment is moved by the same amount that the text
segment is moved.

With the -alf option it is permissible to specify -no_preset. It is also possible for
the -alf option to discover that it can’t preset, for the same reasons as described in

To Preset or Not to Preset, and Creation of the LIC on page 3-7, and the -alf option

acts similarly in that case to what the linker does when it is creating a new loadfile and
discovers that presetting is impossible.

The following are differences between the way the -alf option makes this decision,
and the way it is described in To Preset or Not to Preset, and Creation of the LIC on
page 3-7.

An additional reason that the -alf option cannot preset is that the new LIC would be
too large to fit into the size that the .lic section has in the existing loadfile.

Even if the -alf option is neither rebasing nor presetting, it may still produce
messages about unresolved symbols and it would turn off the EF_TANDEM_PRESET
bit if it previously was on.

The way the -alf option looks for DLLs or import libraries is the same as the way the
linker verifies for them when a file is originally linked the search path for -alf is the
following:

The places specified in -first_L options.

•

The places specified by the DT_TANDEM_RPATH_FIRST entry of the .dynamic

•

section.

The public libraries.

•

eld Manual—527255-009

4-3

Other eld Processing

The location of the existing loadfile.

•

The places specified in -L options.

•

The places specified by the DT_RPATH entry of the .dynamic section.

•

On OSS, if the existing file is a 64-bit data model: /lib64, /usr/lib64, and

•

/usr/local/lib64.
On OSS, /lib, /usr/lib, and /usr/local/lib.

•

On Guardian or OSS, if the existing file is a 64-bit data model: $SYSTEM.YDLL.

•

On Guardian or OSS: $SYSTEM.ZDLL.

•

The -nostdlib option stops the -alf option from looking for public libraries or in
the standard places (i.e., the last two items in the above list), the same as when this
option is used when the linker is creating a new loadfile.

The search path makes use of the information in DT_TANDEM_RPATH_FIRST and

DT_RPATH entries of the .dynamic section so that its search path is similar to that of
rld, and so that the user need not specify any -L or -first_L options. However,

this can only be expected to work when -alf is used in the same environment as
where the program will run, which means not only that it is also the HP NonStop
operating system platform, but that it is the proper version of the operating system, etc.
The -L and -first_L options are provided so that the -alf option can be used
when the places specified by entries in the .dynamic section would not work.

Additional rules about -alf

It is also possible to specify the -rld_L and -rld_first_L options with -alf. As
with the linker’s normal processing of these options, you can specify them multiple
times, and the linker concatenates the strings given. Unlike the linker’s normal
processing of these options, the -alf option does not concatenate these strings with
the ones found in the dt_rpath and dt_tandem_rpath_first entries of the .dynamic
sections of other DLLs that it sees. Instead, if values are specified for -rld_L or -

rld_first_L with -alf, that is used instead of the strings found in the dt_rpath and
dt_tandem_rpath_first entries of the loadfile being updated by the -alf option, when
the -alf option is looking for DLLs. The contents of the dt_rpath and

andem_rpath_first entries of the .dynamic section of the loadfile being updated by

dt_t

the -alf option are not updated by these options. The only way to update these
entries within the loadfile is to relink it from scratch.

Note that the linker still looks in all the places specified above, regardless of the
platform. For example, even though it may not accomplish anything, the linker does

look in the places specified by the dt_rpath and dt_tandem_rpath_first entries of the
.dynamic section, even when running on the PC platform. Colons are still used to

separate names in these entries, even on the PC platform.

If the limit_runtime_paths bit is set in the flags field of the .tandem_info section of the
loadfile then the -alf option does not look in the location of the existing loadfile.

eld Manual—527255-009

4-4

Other eld Processing

Searches performed by the -alf option must always find DLLs rather than archives,
as if -b dllsonly had been specified. It is not possible to specify any -b options
with -alf.

The -alf option supports the -allow_missing_libs option. If a DLL that is listed
in the .liblist section cannot be found, the .liblist entry is left alone.

When the -alf option is operating on a program, it uses the user library the same as
when the linker created the program. By default, the library name stored within the file
is used for the filename of the user library. Or, the -local_libname option can be
specified with -alf, to override the name found within the file (this does not change
the filename that is stored in the file). The -set libname option cannot be specified
with -alf.

Note that the -alf option uses whatever user library name is currently within the file,
or specified by the -local_libname option. It isn’t necessarily the same as the one
that was there when the file was previously preset.

The -change libname option cannot be specified with -alf. If desired, one linker
invocation could be used to change the name stored within the program, by specifying

-change libname, and then a separate linker invocation could give the -alf
option.

Additional rules about -alf

If a program specifies the name of a user library, and the -local_libname option is
not used, then on the PC this always means that the linker can’t find the user library. If
the linker doesn’t have a name for the user library, or, on any platform, if it can’t open
such a file, it is treated like a missing DLL, the same as when a program is created. If
the -local_libname option is used, and the program doesn’t mention any user
library name, that is an error.

By default, the -alf option considers it an error if the loadfile has any relocation sites
in the text segment, which would indicate non-PIC code. However, if the

-update_code option is specified, the -alf option does not consider this an error,
and it updates those relocation sites. The only relocation sites updated in the text
segment are 64-bit addresses of symbols found in the same DLL, which need to be
updated what that DLL is rebased, and is an error if the -update_code option is
specified when the -alf option is updating a program rather than a DLL.

By default, the way the -alf option treats unresolved references depends on the
value of the runtime_unres_checking bits of the .tandem_info section of the loadfile.
Note that, unlike the case of creating a loadfile, the default does not depend on
whether the public DLL registry was found. This can be overridden by specifying the ­unres_symbols option with the desired parameter value. When -unres_symbols
option is specified with -alf, the runtime_unres_checking bits of the .tandem_info
section are unchanged. The -change option can be used (in a separate run of the
linker) to change those bits within the file.

The meanings of the three choices for how unresolved references are handled is the
same for the -alf option as when the object file is first linked, except that the
decision as to whether an unresolved symbol is expected to be code or data is made

eld Manual—527255-009

4-5

Other eld Processing

by looking at the dynamic symbol table of the existing loadfile rather than the ELF
symbol table of an input linkfile.

The following parts of the existing object file potentially need to change when the -alf
option is used without rebasing:

In the ELF header, the EF_TANDEM_PRESET bit may be changed.

•

In the .tandem_info section, the update_timestamp field may be updated. The

•

creation_timestamp and tim_dat fields are not updated. Some other fields may be

reset to zero, as mentioned earlier.

The LIC is updated. It may end up with more or less entries than before. This

•

includes the case that the LIC now is empty, or no longer is empty, because the file

now can or cannot be preset. But the .lic section always has the same size as

before. As mentioned earlier, if this size would not be big enough to contain the
LIC, then the file is not preset, so there is no LIC to worry about.

Throughout the data segment, all the references to undefined symbols are updated

•

as necessary.

Additional rules about -alf

The following additional parts of the existing object file also potentially need to change
when the -alf option is used with rebasing:

In the ELF header, the address of the entry point (the e_entry field) needs to be

•

updated, if this is a DLL that has an entry point. It is updated to the new (rebased)
address of the same procedure that was the main entry point before. The -e
option is not allowed with -alf.

In the program headers, the p_vaddr fields are updated.

•

In the .tandem_info section, the gp_value, the export_digest, and the four fields to

•

tell the addresses of the ctors array, etc., are updated, if they are nonzero. In the
.dynamic section, all the entries that tell addresses of sections of the loadfile, and

the entry that tells the GP value, are updated.
In the .dynsym and .dynsym.gblzd sections, the addresses of all the defined

•

symbols are updated. If they are exported procedures, their st_size fields (telling

the addresses of their official function descriptors) are similarly updated.

In the .rela.dyn and .rela.gblzd sections, the addresses of all the relocation sites

•

are updated.

Throughout the data segment, all the references to symbols defined within the

•

same loadfile are updated. This includes references that are explicitly identified by
relocation table entries as well as things that -alf finds in other ways, such as the

contents of the _ctors, etc. arrays and the official function descriptors.
In the ELF section headers, the sh_addr fields are updated, if they are nonzero.

•

The following additional part of the existing object file would potentially need to be

updated, but only in the case when -alf was rebasing the code and data segments by

different amounts:

eld Manual—527255-009

4-6

Other eld Processing

GP-relative addressing from the gateways to the text segment, specifically, when

•

the gateway contains the 64-bit GP-relative address of the procedure for which it is
the gateway.

The way that the -alf option updates all the items listed above depends on the type
of item:

If the target of the reference is identified by name, -alf updates the reference

•

based on that name.

If the reference site is one that is filled in by the linker, and -alf only knows that it

•

needs to be updated by the amount that this DLL was rebased, -alf determines
which segment previously contained the target of the reference and then updates
the reference site by the amount that that segment moved.

eld reports an error if the existing file cannot be opened for reading. It is possible to

specify the -o option to tell the name of the new output file. If the -o option is not

specified then it defaults to the same name as the existing loadfile. Even if the existing
file is a DLL, its DLL name does not influence the output file name. The output file is
created by the same method as described in The Creation of Output Object Files on

page 2-5, including the use of the -temp_o option or the -must_use_oname option.

Additional rules about -alf

Here is a complete list of the user options that are allowed with the-alfoption:

-allow_missing_libs

-first_L

-L

-local_libname

-must_use_oname

-must_preset

-no_preset

-no_verbose

-no_version_check

-nostdlib

-o

-obey

-public_registry

-rld_first_L

-rld_L

-stdin

-t -temp_o

-unres_symbols

-verbose

-warn

For further information on -alf see Appendix , How -alf Updates DWARF
discussion of the debug.reloc section of the object file.

for a

eld Manual—527255-009

4-7

Other eld Processing

The -set and -change Options

The -set option is used to set certain items in the file being created. These items are
called “file attributes”. The following chart lists the file attributes and tells what they
mean, usually telling the name of the section of this document that provides more
explanation. Each of the attributes is specified together with a parameter to tell the
value of the attribute.

Table 4-1. The -set and -change Options

Attribute Attribute Meaning

data_model For this attribute, allowed values are: ilp32,

The -set and -change Options

lp64, and neutral.

See eld Functionality for 64-Bit
page 4-12.

systype Specifies the target platform personality. See

Target Platforms

libname Specifies the user library name.
highpin
highrequestors
oktosettype
runnamed
saveabend
user_buffers
oktosettype For this attribute the possible values are

inspect For this attribute the possible values are

For these attributes the possible values are
“ON” or “OFF”. These attributes correspond

to flag bits in the .tandem_info section. The

default is ON for highpin and highrequestors,
and OFF for runnamed, saveabend, and
oktosettype. There are several synonyms for
“highrequestors”.

"ON" and "OFF". For compatibility with the
past,

eld accepts this attribute and checks

its syntax, but otherwise this attribute is
ignored.

“ON” and “OFF”. This determines which
debugging facility is made available.
(Internally the corresponding value within the

flags field of the .tandem_info section of the
file is INSPECT_SUBSYSTEM or GARTH,

respectively.) With a TNS/E native file, “ON”
will either start a Visual Inspect session or
pass the file to an already established
session. “OFF” will start Native Inspect.

on page 2-2.

on

eld Manual—527255-009

4-8

Other eld Processing

Table 4-1. The -set and -change Options

Attribute Attribute Meaning

The -set and -change Options

heap_max
mainstack_max
process_subtype
space_guarantee

floattype
float_lib_overrule
CPlusPlusDialect See eld Functionality for 64-Bit

pfssize This attribute has a numerical value. For

rld_unresolved The setting of this attribute tells the -alf

These attributes have numerical values.
These attributes correspond to fields in the

.tandem_info section. If not specified, the

default value in each case is 0.

See the Guardian Procedure Calls Manual

for more information about how to use the
heap_max, mainstack_max, and
space_guarantee attributes. More
information about process_subtype is
provided in the notes following this table.

See Processing of Floating Point Versions

and Data Models on page 4-16.

on

page 4-12.

compatibility with the past, the linker accepts
this attribute and checks its syntax, but
otherwise this attribute is ignored.

option, as well as rld, how to treat

unresolved symbols. See Handling

Unresolved References on page 3-8.

incomplete For this attribute the only allowed (and

therefore required) parameter is “ON”. If this
attribute is specified, it means that the import
library being created by the linker is
incomplete. The incomplete attribute only
applies to import libraries. The -change flag
can be used to turn it ON, but cannot turn it
off. See Creating Import Libraries
page 3-11.

on

The only attributes of the -set option which can be specified with the -r option are
data_model, floattype, and process_subtype.

The linker produces a warning message if it is creating a loadfile with highpin on
and any of the DLLs or import libraries that it has opened have highpin off.

The -libname option is a synonym for -set libname.

When eld builds a new object file from a set of input linkfiles it combines the values of
the process_subtype attribute found in those input linkfiles. If an input linkfile has a

.tandem_info section that is abbreviated to four bytes then its process_subtype is

considered to be zero. A non-zero value in one input file is accepted in preference to a
zero value in another input file, but two distinct non-zero values among the input files

eld Manual—527255-009

4-9

Other eld Processing

are considered inconsistent. If -set process_subtype is specified then the value
specified is placed into the output file and if any of the input linkfiles had a nonzero
process subtype different from that then a warning message is produced. On the other
hand, if -set process_subtype is not specified then it is an error if the input
linkfiles were inconsistent, and if they are consistent then the value from the input
linkfiles is placed into the output file.

The -set incomplete on option is only allowed when the linker is creating an

import library that represents a single DLL. It tells the linker to create an incomplete
import library, rather than a complete one. This could either be when the linker is
creating the import library at the same time as the linker is creating the corresponding
DLL, or when the linker is creating the import library for a DLL that already existed. In
either case, all the other things that are controlled by the -set option are the same in
the import library as in the corresponding DLL.

All the other attributes listed above, except for libname, can be specified whether
building a program or a DLL, even though some of them may be meaningless for
DLL's. The libname attribute can only be specified when building a program.

The -set and -change Options

The -change option is used to alter the same attributes that can be set by the -set
option. The difference is that -change modifies an existing file, whereas -set is used
when a new file is being created. The -change option takes the same parameters as

-set, plus the name of the existing file.
The -change option can be used with a linkfile, loadfile, or import library, with the

following rules:

The -change attributes that are allowed with a linkfile are the data_model

•

and floattype attributes.
The -change libname attribute is only allowed with programs. The linker

•

places the name specified by the-change libname option into the
.tandem_info section of the program that it is creating. The linker also converts
the name to upper case, if not done already. On Guardian APIs,single quotes
do not work because they are not recognized by TACL; therefore, it is not
important to specify them.

The incomplete attribute of the -change option is only allowed with import

•

libraries. This tells the linker to demote the import library to an incomplete one,
if it was a complete one before. There is no way to “un-demote” an incomplete
import library.

The data_model attribute of the -change option is only allowed with DLLs

•

and import libraries.

It is possible to give an empty string, or a string consisting just of a single double-quote
character ("), as the user library name in the -change libname option. This makes it
possible to remove the user library name from an existing program. From the PC or
OSS command line you can use two double-quote characters ("") to pass an empty
string. However, on the TACL command line, when you use two double-quote
characters (""), a single double-quote character (") gets passed to the process. That is

eld Manual—527255-009

4-10

Other eld Processing

why eld also allows a single double-quote character (") to be given with -change
libname, and interprets it as an empty string. Note that this is only allowed with

-change libname, not with -set libname.

Except for the items listed above, there are no restrictions on which attributes can be
specified. Note that some attributes can be specified for DLLs even though they are
meaningless for DLLs.

Note that it is permissible to change any of the attributes of an import library, even
though only a few of these attributes are significant in an import library. (The ones that
are “significant” are the ones that the linker might look at when building a client of that

import library in order to check for consistency, namely, the highpin bit, the floating

point type, and the C++ dialect, as well as the bit that tells whether the import library is
complete.)

The -change option performs the same version number checking on a loadfile or

import library as is described in Input Object Files on page 2-12.

In all cases, the -change option only changes the specific information specified, and
has no other consequences. For example, when -change libname is specified for a

program, it only changes the user library name that is shown in the program. If the
program was previously preset, using a different user library, that fact is unchanged.
The newly specified user library would be used in the future when this program is run.
At that time, if the user library found with that name was not equivalent to (i.e.,
contained the same export digest as) the user library that had been used when the
program was preset, then the program would not have been preset correctly for its
runtime environment and would need to be updated accordingly. That is the same as
what would happen if the same user library filename were still being used, but the
contents of that user library file had changed (i.e., so that its export digest was
different).

The -set and -change Options

The -change option overwrites the existing file without recreating it. eld reports an

error if the file cannot be opened for update. If an error occurs the specified change
may or may not have taken place, but the file will not have been modified in any other
way.

It is possible for the command stream to have multiple -change options. Each one is

executed independently, if the previous one succeeds, even if they refer to the same

filename. For example, two -change options may both specify the same attribute,
such as -change highpin, and they don’t have to agree on the value to which this
attribute is being set, whereas such a consistency check would occur if -set

highpin were specified more than once. The only other options allowed with the ­change option are - no_verbose, -obey, -stdin, -verbose, and -warn.

Note: There are no -set or -change options that affect the procedure attributes that
are found in the .procinfo section of a linkfile or the stack unwinding information of a
loadfile. However, the -e option can be used to turn on the MAIN attribute in the
.procinfo section of a linkfile that is being created by the linker.

eld Manual—527255-009

4-11

Other eld Processing

eld Functionality for 64-Bit

Object files can be 32-bit, 64-bit, or neutral. When eld is creating a new
object file out of a set of linkfiles, the desired data model for the output file is specified
by the following option:

-set data_model [value]
where value can be ilp32, lp64, or neutral.
For lp64 input linkfiles, it is considered as an error, if -set data_model ilp32” is

specified. Conversely, for ilp32 input linkfiles, it is considered as an error, if lp64 is
specified. Specifying neutral, does not verify the data models for the input linkfiles and
the output file which is marked as neutral. The neutral option is allowed only while
creating a linkfile or a DLL, and not for a program.

If the input linkfiles contains a combination of ilp32 and lp64 linkfiles, it is considered
as an error if the -set data_model option is not specified. If this error does not
occur, either the output file is marked with the data models (ilp32 or lp64) which
occur within the input linkfiles, or is marked as neutral if all the input linkfiles are
neutral.

eld Functionality for 64-Bit

The -change data_model neutral option marks an object file neutral,
regardless of how it was marked before. This is allowed for linkfiles and DLL’s, but not
for programs.

The searching that is done for -l options or for liblist entries depends on the data
model of the file that is being created or processed by the -alf option, as discussed
in this manual.

When eld creates an import library that represents a single (non-implicit) DLL, the
import library is given the same data model as that DLL.

The import library that represents the implicit DLL’s is always neutral.

Checking the C++ Language Dialect

To build a new linkfile or loadfile, the linker performs consistency checks of C++
language dialects.

In a linkfile, the st_other fields of ELF symbol table entries tell which C++ language

dialects are used by that object file, if any. If more than one C++ dialect occurs among
all the input linkfiles, that is an error.

By default, if some dialect of C++ occurred in the input linkfiles, then that value is

placed into the .tandem_info section when eld is building a loadfile. If none of the
input files used C++ then the value cppneutral is placed into the .tandem_info

section.
CPlusPlusDialect is an attribute accepted by the -set option, and the only allowed

value of the attribute is cppneutral. Also, this option is only allowed when creating a
loadfile. If specified, it means that the loadfile will be marked cppneutral, even if the

eld Manual—527255-009

4-12

Other eld Processing

input files contained C++. An informational message is generated if the input files
contained C++.

When eld is creating a loadfile it also performs C++ dialect checking against all the
DLL's that it sees as part of that load. The check is that no DLL has the opposite C++
dialect from that seen in an input linkfile.
Note that the use of -set CplusPlusDialect cppneutral does not affect this
check. If this check fails a warning message is generated; it is not considered an error
because different DLL's might be used at runtime.

Renaming Symbols

The -rename option affects how the linker treats each input linkfile as it is reading it in.
This option takes two parameters, symbol-1 and symbol-2. The option has no effect
unless this linkfile defines a global symbol named symbol-1. eld reports an error if this
same linkfile also defines a global symbol named symbol-2. The linkfile that defined
symbol-1 is now considered to define a symbol named symbol-2, with the same
properties that symbol-1 had. The linkfile is still considered to declare a symbol named
symbol-1, with the same properties as before, except that it is now an external

reference rather than a definition.

Renaming Symbols

As a result, if the object file being built would have defined a symbol named symbol-1,
it will now define symbol-2 instead. If there were references to symbol-1, those will still
refer to symbol-1, and therefore they could not be resolved within this same object file.
If a new linkfile is being built with the -r option, a future link could combine this linkfile
with another one that supplied a definition of symbol-1, to satisfy such references. Or,

in general, the references could be satisfied in other DLLs.

One purpose of this option is to allow one copy of symbol-1 to be replaced by another
one, without having to recompile the source that created the linkfile containing symbol-

1. For example, the given object file that defines symbol-1 may be put through the
linker with the -r and -rename options to create another linkfile that no longer
defines symbo1, and then that linkfile could be linked with another one that provides a
different definition of symbol-1. For this purpose it is not necessary that the name
symbol-2 ever be referenced. However, when a procedure is renamed, the new version
of symbol-1 might wish to do the same things that the older symbol-1 would have
done, plus some new things. It could do this by calling symbol-2 to do the old stuff, and

having additional code for the new stuff.

Any number of -rename options may be in the command stream. They all apply to all

the input linkfiles, regardless of where they occur in the command stream. As each
input linkfile is processed, the linker does the processing described above for each

-rename option, in the order that the -rename options appeared in the command

stream.

eld Manual—527255-009

4-13

Other eld Processing

Creating Linker-Defined Symbols

Predefined Symbols on page A-14 lists the symbols that are automatically defined by

the linker when it creates a loadfile, and what they mean. The linker resolves
references to these symbols by using the value of the symbol as if it was an address.

Creating Linker-Defined Symbols

As mentioned in Creating the MCB

on page 4-15, eld reports an error if you define a

symbol named _MCB. For other linker-defined symbols the linker puts out a warning if

they are defined by the user. Note that, if such a symbol is defined by the user, then
the linker uses the symbol defined in the linkfile in the usual way, rather than creating
its own symbol of this name with a special meaning.

Updating Or Stripping DWARF Symbol Table Information

The linker concatenates the DWARF symbol tables of its input linkfiles into the DWARF
symbol table of its output file.

The linker fills in the addresses of symbols found in the DWARF symbol table
information. Such relocation sites are described in linkfiles by the same kinds of
relocation table entries as any other data, so that the linker doesn’t need to understand
the format of the DWARF symbol table to do this. In loadfiles, the addresses in the
DWARF symbol table are the usual addresses, not segment-relative addresses.

When there are multiple copies of a symbol, the DWARF addresses for the unused
copies are set to -1, as discussed in Accepting Multiply-Defined Symbols on
page 3-17.

The stripping of symbols information means that the linker does not create the DWARF

symbol table information in its output file(s). The reason to do this is to make object
files smaller, when the user is not concerned with debugging. For compatibility with the

past, this can be done with either the -s or -x option. In our TNS/R implementations,

-s strips all the symbols information, whereas -x strips only the symbols information

that the linker doesn’t need, but the distinction has disappeared with the segregation of
the debugging information into the DWARF symbol table. In other words, the TNS/E
linker does not depend on information in the DWARF symbol table for any of its other
activities.

When the linker is creating a linkfile and stripping the DWARF symbol table the linker
also omits the corresponding relocation table sections.

When the linker is creating an import library, that import library may or may not contain
DWARF symbol table information. See Creating Import Libraries on page 3-11.

The -strip option tells the linker to remove the DWARF symbol table from a loadfile

or import library that already exists. This option creates a new file in place of the old
file.

It is possible for the command stream to have multiple -strip options. Each one is

executed independently, if the previous one succeeds. The only other options allowed

with the -strip option are -must_use_oname, -no_verbose,

-no_version_check, -obey, -stdin, -temp_o, -verbose, and -warn. If

eld Manual—527255-009

4-14

Other eld Processing

Modifying the Data Sections that Contain Stack

Unwinding Information

there are multiple -strip options, the temporary filename specified by -temp_o

applies to all of them.

The ELF symbol table can never be stripped from a linkfile, and the .dynsym and
.dynsym.gblzd sections can never be stripped from a loadfile, because they are

needed by the linker and/or runtime loader.

Modifying the Data Sections that Contain Stack Unwinding
Information

Linkfiles may contain an unwind function section, an unwind information section, and a
relocation table section for that unwind function section. The linker concatenates these
sections when creating another linkfile. The linker similarly concatenates the

information in .procinfo and .procnames sections.

When building a loadfile, the linker creates an unwind function section, unwind
information section, and string space. The format of the unwind function section in a
loadfile is different from the format that it has in a linkfile, containing additional

information that the linker obtains from the .procinfo and .procnames sections of its

input linkfiles.

If there were multiple copies of procedures, the information about unused copies is

omitted from the .procinfo and unwind function sections of linkfiles, and from the

unwind function sections of loadfiles. In the linkfile case, that also means doing
something about the corresponding relocation table entries.

Creating the MCB

The linker creates the MCB (“master control block”) as additional data in the .data
section. The internal name of the MCB is _MCB (one underscore), so this name can be
used to reference the MCB. The linker only creates the MCB if it is building a program,
and only if there is a reference to the symbol named _MCB.
symbol named _MCB is defined in any of the linker’s input object files, regardless of

the type of file the linker is creating.

Two linker options that specifically affect the value placed into the MCB are

-ansistreams and -nostdfiles. The value that the linker has decided to place

into the ELF header to describe the floating point type is also reflected in the MCB.

The TNS/E linker considers it an error if either of the above options is specified when

the linker is not creating a program. The option -no_stdfiles is accepted as a
synonym for -nostdfiles.

Further information on the MCB may be found in The MCB (Master Control Block)
page A-14.

eld reports an error if a

on

eld Manual—527255-009

4-15

Other eld Processing

Processing of Floating Point Versions and Data

Processing of Floating Point Versions and Data Models

When the linker builds a new linkfile or loadfile it performs consistency checks of
floating point versions. These checks use the floating point bits that are found in the

e_flags field of the ELF header.

The linker determines whether the input linkfiles are consistent, meaning that they do
not contain a mixture of both the tandem and ieee floating point types. If they are

consistent then the result type is determined to be whichever of tandem or ieee
occurred, or neutral if neither occurred.

If the -set floattype option is used, that determines the value that is placed into
the output linkfile or loadfile. The three values that can be specified with the -set

floattype option are ieee, neutral, and tandem, and they have the synonyms
ieee_float, neutral_float, and tandem_float, respectively. An informational

message is generated if the input files were not consistent, or if they were consistent
but with a result type different from what the option specified.

If a program is marked neutral, the HP NonStop operating system and CRE
consider that to mean the same thing as tandem. If the linker is creating a program
and -set_floattype neutral has been specified then the linker will put out a
warning message to say that floating point type neutral actually means tandem to
the HP NonStop operating system and CRE.

Models

If the -set floattype option is not used, eld reports an error if the input files are

not consistent. If they are consistent, the result type is placed into the output file.

When the linker is building a loadfile, the -set float_lib_overrule option may
be used to turn on the EF_TANDEM_FLOA T_LIB_OVERRULE bit in the ELF header of

the loadfile. The linker allows this bit to be set in both programs and DLLs.

The linker performs additional floating point checks with regard to DLLs when it is
creating a new loadfile, as described in the following paragraphs. The same checks are
performed by the -alf option when they are updating an existing loadfile. These
checks result in warning messages, not errors, because different DLLs may be used at
runtime.

If the linker is building a program, or updating it with -alf, the intention is to be
consistent with the checks that the HP NonStop operating system will do. So, there is
no checking against DLLs if the linker has been told to turn on the
FLOAT_LIB_OVERRULE bit in the program. If this bit is not to be turned on then the
linker checks the program’s floating point type against all the DLLs that it has opened.
All DLLs must either be neutral or have the same floating point type as the one
indicated in the program. As mentioned above, if the program is marked neutral, the
linker considers that to mean tandem.

If the linker is building or updating a DLL then it checks that all the DLLs seen by the
linker, including the DLL that is being created or updated, do not contain a mixture of
both tandem and ieee.

eld Manual—527255-009

4-16

Other eld Processing

Checks are only performed against DLLs that the linker actually saw. For example, the
linker is not required to search for indirect DLLs if it is not presetting and not checking
for unresolved symbols, so in that case it is not required to perform floating point
consistency checking against such indirect DLLs.

Whenever the linker builds a new linkfile or loadfile it checks for the consistency of the
data model among its input linkfiles, because the two data models cannot be
intermixed in the same loadfile, and the data model of the input linkfiles determines the
data model for the output file. More specifically, at the present time, the linker does not
allow the 64-bit data model at all, but in the future that will be relaxed. There is no
checking for consistency against DLLs, because loadfiles with different data models
are allowed in the same process.

Specification of the Main Entry Point

There are two ways to specify the main entry point of a loadfile. One is to use the -e

option, specifying the name of a procedure. The other way is for a procedure to have
the MAIN attribute.

Specification of the Main Entry Point

In a program, the e_entry field is filled in with the address of the real code for the main

entry point. In a DLL, if it has a main entry point, then that procedure must have an

official function descriptor, and the e_entry field contains the address of that official

function descriptor.

When the -e option is specified the linker checks that it is the name of a procedure

that is defined in this object file (otherwise it is an error). eld reports an error if this

procedure has the CALLABLE or KERNEL_CALLABLE attribute. Additional rules

depend on the type of file that the linker is building:

If the linker is building a program then eld reports an error if no main entry

•

point has been specified by either of the above methods. The linker will put out

a warning if the -e option is used and the program has a procedure with the
MAIN attribute, unless the same procedure is indicated in both cases. The
linker uses the -e option to determine the main entry point, overriding the fact
that a procedure had the MAIN attribute.

If the linker is building a DLL then eld reports an error if any procedure has the

•

MAIN attribute. However, the -e option is allowed. If the -e option is not
provided then the e_entry field contains zero.

If the linker is building a linkfile then the -e option has a different purpose.

•

Namely, it turns on the MAIN attribute in the .procinfo entry for the specified
name. The e_entry field of the ELF header in a linkfile always contains zero.

When the linker is building a loadfile

has the MAIN attribute, unless the -allow_multiple_mains option is used. When
there are multiple procedures with the MAIN attribute, and this is not an error, the linker
pays attention to the MAIN attribute on the first procedure that it sees with it. This

ordering is implied by the order in which the linker finds linkfiles from the command

stream and the ordering of the entries in the .procinfo sections of the linkfiles.

eld reports an error if more than one procedure

eld Manual—527255-009

4-17

Other eld Processing

When building a program in C or C++, and using the standard runtime library support
provided by these compilers, the usual method is to place in the linker command
stream an object file that is also supplied with these compilers and contains a

procedure that has the MAIN attribute. Users who invoke the linker through the

compiler may not realize this, because the compiler automatically adds the file name to
the linker command stream when it invokes the linker. Thus, for most users of C or
C++, the main procedure is not a procedure they’ve written themselves, and there is no

need to use the -e option. If you use the -e option and specify the wrong procedure
(for instance, the procedure named main that you’ve written) as the main entry point,

and you ignore the linker warning about this, then you will probably build a program
that will not run correctly because it will not start at the proper point.

Specifying Runtime Search Path Information for

Specifying Runtime Search Path Information for DLLs

The linker fills in the DT_RPATH and DT_TANDEM_RPATH_FIRST entries of the
.dynamic section to tell rld where to find DLLs at load time. Each of these fields is a

list of places to look, where a colon separates the names in the list. The individual
names cannot contain colons. The commands used for filling in these entries, and the
purposes of these entries, are as follows:

DLLs

DT_RPATH tells places to look after looking for public DLLs. The -rld_L

•

option specifies a string to place into DT_RPATH. -rpath is accepted as a
synonym for -rld_L.

DT_TANDEM_RPATH_FIRST tells places to look before looking for public

•

DLLs. The -rld_first_L option specifies a string to place into
DT_TANDEM_RPATH_FIRST.

Each of the -rld_L and -rld_first_L options may be specified multiple times in
the command stream. The linker concatenates the information provided, in the order
the options were given. The linker understands that names are separated by colons,
and removes duplicate names from the list. eld reports an error if you specify these
options with -r.

Note that the linker does not try to detect names that are “invalid” for any reason and
remove them from the list.

Note that the -rld_L and -rld_first_L options are allowed whether building a
program or a DLL. rld only uses this information found in programs. However, the

linker looks at this information in each DLL that it uses in a link that is creating a
loadfile. The linker concatenates this information from DLLs the same as if the
corresponding values had been given in the command stream, considering them to
come at the end of the command stream and in the same order as the DLLs were
found by the linker.

The -limit_runtime_paths option is used to tell rld that its algorithm for looking

for DLLs is not to be concerned with the location of the program nor with any runtime
path specifications. When this option is specified the linker turns on the

LIMIT_RUNTIME_PATHS bit in the flags field of the .tandem_info section.

eld Manual—527255-009

4-18

Other eld Processing

The DT_RPATH and DT_TANDEM_RPATH_FIRST entries in the .dynamic section are
also used by -alf to decide where to look, although in this case they can be
overridden by giving the -rld_L or -rld_first_Loptions with -alf.

Merging Source RTDUs

Each input linkfile may contain a set of source RTDUs, which are used in the
implementation of SQL/MP. If so, then the linker creates source RTDUs in its output
file. This mostly involves concatenating the corresponding sections, although there are
also pointers into RTDU string spaces that need to be updated appropriately.

Merging Source RTDUs

eld Manual—527255-009

4-19

Other eld Processing

Merging Source RTDUs

eld Manual—527255-009

4-20

5 Summary of Linker Options

This section lists all the options supported by the TNS/E linker. For each one the
complete syntax is shown, a brief statement of its function is given, and a hyperlinked
reference is given to the main discussion of it elsewhere in this manual.

-alf <filename>

Rebase and/or rebind an existing loadfile, recreating the file.
See Additional rules about -alf on page 4-3.

-all

Use all members from archives. See Using Archives on page 2-16.

-allow_duplicate_procs

Do not consider it an error if there are multiple definitions of procedures with the
same name. See Accepting Multiply-Defined Symbols on page 3-17.

-allow_missing_libs

Do not consider it an error if a -l option cannot be resolved, except in situations
where -b static is in effect. See How the Linker Finds Its Input Files and

Creates the .liblist Section on page 2-12.

-allow_multiple_mains

Do not consider it an error if more than one procedure has the MAIN attribute.
See Specification of the Main Entry Point on page 4-17.

-ansistreams

At runtime, the program will use the ANSI version of C I/O.
See Creating the MCB on page 4-15.

-b { dllsonly | dynamic | static }

These options specify whether the linker accepts DLLs and/or archives.
See How the Linker Finds Its Input Files and Creates the .liblist Section on
page 2-12.

-b { globalized | localized | semi_globalized | symbolic }

These options affect how references are resolved across loadfiles.
See Overview on page 3-1.

-call_shared

Create a program. See Output Object Files on page 2-4.

eld Manual—527255-009

5-1

Summary of Linker Options

-change <attribute> <value> <filename>

Change the parts of an existing object file corresponding to things that the -set
option would set up. The <attribute> and <value> have the same possibilities as for
the -set option shown below. See The -set and -change Options on page 4-8.

-check_registry <filename>

Use the specified DLL registry to tell where the DLL being built must be placed in
memory. See Using a DLL Registry on page 2-8.

-cross_dll_cleanup

Discard a procedure if found in another DLL. For more information, see Using the -

cross_dll_cleanup option on page 3-19.

-d <hexadecimal address>

Use the specified value as the starting address of the data (constant) segment.
See Creating Segments of the Output Loadfile on page 2-6.

-data_resident

This is a special option that may be used when building a “proto-process”, also
known as a “sysgen process”.

-dll

synonym for -shared.

-dllname

synonym for -soname.

-e <symbol name>

Use the address of the specified procedure as the main entry point.
See Specification of the Main Entry Point

on page 4-17.

-error_unresolved

synonym for -unres_symbols error.

-export

synonym for -exported_symbol.

-export_all

Export all symbols that one might normally want to have exported without naming
them explicitly. See Specifying Which Symbols to Export, and Creating the Export

Digest on page 3-20.

eld Manual—527255-009

5-2