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 onetime 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
Loading...