HP nld, noft Users Manual

nld and noft Manual

Abstract

This manual explains how to use the following TNS/R native object file utilities: nld
(T6017), which links and changes object file attributes; noft (T9626), which displays
object files; ar (T8629), which creates and maintains archives of object files; and
strip (T8629), which removes unnecessary information from loadable object files
(loadfiles) in the HP NonStop™ Kernel Open System Services (OSS) environment.

Product Version

nld D44
noft D45
ar D43
strip D43

Supported Release Updates (RVUs)

This manual supports D45 and G06 and all subsequent RVUs until otherwise indicated
in a new edition.

Part Number Published

520384 -003 May 2003

Document History

Part Number Product Version Published

426922- 001 nld D44, no ft D4 2, ar D43 November 2000
427686- 001 nld D44, no ft D4 2, ar D43, strip D 43 February 2001
520384- 001 nld D44, no ft D4 2, ar D43, strip D 43 July 2001
520384- 002 nld D44, no ft D4 2, ar D43, strip D 43 February 2002
520384- 003 nld D44, no ft D4 5, ar D43, strip D 43 May 2003

Hewlett-Packard Company—520384-003

i

nld and noft Manual

Glossary Index Examples Tables

What’s New in This Manual xi

Manual Information xi
New and Changed Information xii

About This Manual xv

Audience xv
Related Reading xvi
Your Comments Invited xvi
Notation Conventions xvii

1. Introduction to the Utilities

Native Object Files 1-2
nld 1-2
noft 1-4
ar 1-5
strip 1-5

2. nld Util ity

Running the nld Utility in the Guardian Environment 2-1
Running the nld Utility in the OSS Environment 2-3
Running Windows nld on the PC

2-4

Components of Windows nld

2-4

Directory Structure of Windows nld 2-4
Compilers That Can Launch Windows nld 2-5
How Windows nld Differs from nld 2-5
How the ETK Command-Line and GUI Interfaces Differ 2-6
Command-Line Interface Linking Options 2-7

Changing the Target Environment 2-8
Creating Loadfiles and Linkfiles 2-8

Contents

nld and noft Manual—520384-003

ii

2. nld Utility (continued)

2. nld Util ity (continued)

Linking Programs 2-9

C Programs 2-9
C++ Programs 2-10
COBOL Programs 2-12
pTAL Programs 2-13
Mixed-Language Programs 2-13
Programs With Embedded NonStop SQL/MP 2-13

Linking User Libraries 2-13
Linking Shared Run-Time Libraries (SRLs) 2-15

Specifying SRLs 2-16
Determining Which SRLs Programs Require 2-17

Linking Archive Files 2-21
Linking Floating-Point Programs 2-22

Link-Time Consistency Checking 2-23
Run-Time Consistency Checking 2-25
Linking Mixed-Language Pro gram s 2-26

Searching for Archives and SRLs With Simple Filenames 2-27
Dynamic and Static Linking 2-28
Str i pping Sym bol Informa tion 2-29
nld Compilation Rules 2-29

Case Sensitivity 2-29
Local and Shared Symbols 2-30
Declaration and Definition 2-31

3. nld Options

-allow_duplicate_procs 3-2

-allow_missing_libs 3-3

-allow_multiple_mains 3-3

-ansistreams 3-3

-bdynamic 3-3

-bstatic 3-4

-change 3-4

-e 3-5

-elf_check 3-5

-export 3-5

-fl or -obey 3-6

-import 3-6

-l or -lib 3-7

Contents

nld and noft Manual—520384-003

iii

3. nld Options (continued)

3. nld Options (continued)

-L or -libvol 3-8

-libname 3-9

-nostdfiles 3-9

-nostdlib 3-9

-noverbose 3-10

-NS_extent_size 3-10

-NS_max_extents 3-10

-o 3-11

-r 3-11

-rename 3-12

-s 3-12

-set 3-13

-stdin 3-15

-strip 3-16

-ul 3-16

-verbose 3-16

-x 3-17

-y 3-17

4. noft Utility

Running the noft Utility in the Guardian Environment 4-1
Running the noft Utility in the OSS Environment 4-3
Listing Object Files 4-4
Dumping Object Files 4-5
Controlling the noft Environm ent 4-5
Debugging With noft 4-7

5. noft Options

Break Key 5-3
! (Exclamation Point) 5-4
CD 5-5
COMMENT 5-5
DUMPADDRESS or DA 5-6
DUMPOFFSET or DO 5-8
DUMPPROC or DP 5-10
ENV 5-13
EXIT or E 5-13
FC 5-14

Contents

nld and noft Manual—520384-003

iv

5. noft Options (continued)

5. noft Options (continued)

FILE or F 5-15
HELP or ? 5-17
HISTORY or H 5-20
LAYOUT 5-21
LISTATTR IBUTE or LA 5-22
LISTCOMPILERS or LC 5-23
LISTOP TI MIZE or LO 5-26
LISTPROC or LP 5-27
LISTSOURCE or LS 5-29
LISTSRLEXPORTS or LLE 5-30
LISTSRLFIXUPS or LLF 5-30
LISTSRLINFO or LLI 5-31
LISTUNREFERENCED or LUR 5-32
LISTUNRESOLVED or LU 5-35
LOG 5-38
OBEY 5-39
OUT 5-39
QUIT or Q 5-40
RESET 5-41
SET 5-42
SHOW 5-47
SYSTEM or VOLUME 5-48
XREFPROC or XP 5-49

6. ar Utility

7. strip Utility

8. Native Object File Structure

Code and Data Segments 8-1
MDEBUG Section 8-2

9. Converting From Binder to nld and noft

Object File Differences 9-1
Linking Unit Differences 9-2
Comparing Binder Commands to nld Options 9-3
Comparing Binder Commands to noft Options 9-6

Contents

nld and noft Manual—520384-003

v

10. nld Diagnostic Messages

10. nld Diagnostic Messages

General Information 10-1
Terms That Appear in nld Diagnostic Messages 10-2
Fatal Errors 10-12
Nonfatal Errors 10-61
Warnings 10-69
Informational Messages 10-77

11. noft Diagnostic Messages

Fatal Errors 11-1
Data Errors 11-4
Warnings 11-18
Syntax Errors 11-22

12. ar Diagnostic Messages
A. Sample nld and noft Session

Example Program A-1

Header Files A-2
Source Module MAINC A-3
Source Module MODULE1C A-3
Source Module MODULE2C A-5
User Library UTILC A-6

Compilation Commands A-6
nld Command Examples A-7
Program Output A-8
noft Command Examples on a Linkfile A-9

FILE

A-9

LISTATTRIBUTE

A-9

LISTCOMPILERS A-10
LISTPROC A-10
LISTSOURCE A-12
LISTSRLINFO A-13
LISTUNRESOLVED A-14

Contents

nld and noft Manual—520384-003

vi

A. Sample nld and noft Session (continued)

A. Sample nld and noft Session (continued)

noft Command Examples on a Loadfile A-15

FILE A-15
LISTATTRIBUTE A-16
LISTCOMPILERS A-17
LISTPROC A-17
LISTSOURCE A-18
SET SORT A-19
LISTSRLINFO A-19
LISTUNRESOLVED A-20
LISTOPTIMIZE A-21
XREFPROC A-21
DUMPPROC A-24
LISTSRLFIXUPS A-26
LISTSRLEXPORTS A-27
LISTSRLFIXUPS A-27

Glossary
Index

Examples

Example 2-1. Creating a Loadfile (Guardian) 2-2
Example 2-2. Changing the HIGHPIN Attribute (Guardian) 2-2
Example 2-3. Creating a Loadfile (OSS) 2-3
Example 2-4. Creating a User Library (OSS) 2-3
Example 2-5. Creating a Program File (OSS) 2-3
Example 2-6.

Creating an Executable C Program (OSS) 2-4

Example 2-7.

Running nmcobol and Launching Windows nld 2-5
Example 2-8. Running nld from the Command Prompt 2-6
Example 2-9. Creating a Program for the Guardian Environment (OSS) 2-8
Example 2-10. Creating an Executable C Program 2-10
Example 2-11. Linking a Mixed-Language Program With IEEE Floating-Point

Format 2-26
Example 2-12. Searching for ZCRTLSRL and ZCRESRL (Guardian) 2-28
Example 2-13. Searching for ZCRTLSRL and ZCRESRL (OSS) 2-28
Example 2-14. Searching for ZCOBSRL and ZCRESRL (OSS) 2-28
Example 4-1. noft Command Line 4-3
Example 4-2. Interactive noft Session Equivalent to Example 4-1 on page 4-3 4-4
Example 4-3. C Program 4-7

Contents

nld and noft Manual—520384-003

vii

Examples (continued)

Examples (continued)

Example 4-4. Optimize 0 Listing 4-8
Example 4-5. Optimize 1 Listing 4-9
Example 4-6. Optimize 2 Listing 4-10
Example 5-1. CD Option 5-5
Example 5-2. DUMPADDRESS Option 5-7
Example 5-3. DUMPOFFSET Option 5-9
Example 5-4. DUMPPROC Option 5-12
Example 5-5. Displaying Current noft Environment Settings 5-13
Example 5-6. FILE Option 5-16
Example 5-7. HELP ALL Option 5-18
Example 5-8. HELP SET HISTORYBUFFER 5-19
Example 5-9. HELP Without Options 5-19
Example 5-10. HISTORY Option 5-20
Example 5-11. LAYOUT Option 5-21
Example 5-12. LISTATTRIBUTE Option for Non-PIC Object File 5-22
Example 5-13. LISTATTRIBUTE Option for PIC Object File 5-23
Example 5-14. LISTCOMPILERS Option (BRIEF) 5-24
Example 5-15. LISTCOMPILERS Option (DETAIL) 5-24
Example 5-16. LISTOPTIMIZ E Option 5-26
Example 5-17. LISTPROC Option (BRIEF) 5-28
Example 5-18. LISTPROC Option (DETAIL) 5-28
Example 5-19. LISTSOURCE Option (BRIEF) 5-29
Example 5-20. LISTSOURCE Option (DETAIL) 5-30
Example 5-21. LISTSRLINFO Option (BRIEF) 5-31
Example 5-22. LISTSRLINFO Option (DETAIL) 5-31
Example 5-23. pTAL Program for Example 5-24 and Example 5-29 5-33
Example 5-24. LISTUNREFERENCED Option for Example5-23 pTAL

Program 5-33
Example 5-25. C Program for Example 5-26 and Example 5-30 5-34
Example 5-26. LISTREFERENCED Option for Example 5-25 C Program 5-34
Example 5-27. LISTUNRESOLVED Option (BRIEF) 5-36
Example 5-28. LISTUNRESOLVED Option (DETAIL) 5-36
Example 5-29. LISTUNRESOLVED Option for Example 5-23 pTAL Program 5-37
Example 5-30. LISTUNRESOLV ED Option for Example 5-25 C Program 5-37
Example 5-31. Effect of EXCLUDE on LISTUNRESOLVED Option 5-37
Example 5-32. LOG Option 5-38
Example 5-33. OBEY Option 5-39
Example 5-34. OUT Option When “?” is Specified 5-40

Contents

nld and noft Manual—520384-003

viii

Examples (continued)

Examples (continued)

Example 5-35. Resetting Target Object File Parameters to Their Default

Values 5-41
Example 5-36. SHOW Option 5-47
Example 5-37. XREFPROC Option (BRIEF) 5-51
Example 5-38. XREFPROC Option (DETAIL) 5-51
Example 5-39. XREFPROC Option (for C Program in Example 5-25) 5-52
Example 5-40. XREFPROC Option for Non-PIC Object File With “Reference”

Indicators (CALLS and DETAIL) 5-52
Example 9-1. Linking Two Object Files in Binder and nld (Simple Case) 9-4
Example 9-2. Linking Two Object Files in Binder and nld (Less Simple Case) 9-5
Example 9-3. Setting the INSPECT Attribute in Binder and nld 9-5
Example A-1. Header File GLOBALSH With Edit Line Numbers A-2
Example A-2. Header File MODULE1H With Edit Line Numbers A-2
Example A-3. Header File MODULE2H With Edit Line Numbers A-2
Example A-4. Header File UTILH With Edit Line Number A-3
Example A-5. Source Module MAINC With Edit Line Numbers A-3
Example A-6. Source Module MODULE1C With Edit Line Numbers A-4
Example A-7. Source Module MODULE2C With Edit Line Numbers A-5
Example A-8. User Library UTILC With Edit Line Numbers A-6
Example A-9. Linking an Executable User Library A-7
Example A-10. Linking a Program File A-7
Example A-11. Sample Program Output A-8
Example A-12. FILE Option (Linkfile) A-9
Example A-13. LISTATTRIBUTE Option (Linkfile) A-9
Example A-14. LISTCOMPILERS Option (Linkfile) A-10
Example A-15. LISTPROC Option (Linkfile) A-11
Example A-16.

LISTSOURCE Option (Linkfile) A-12
Example A-17.

LISTSRLINFO Option (Linkfile) A-13
Example A-18. LISTUNRESOLVED Option (Linkfile) A-14
Example A-19. FILE Option (Loadfile) A-15
Example A-20. LISTATTRIBUT E Option (Load file) A-16
Example A-21. LISTCOMPILERS Option (Loadfile) A-17
Example A-22. LISTPROC Option (Loadfile) A-17
Example A-23.

LISTSOURCE Option (Loadfile) A-18
Example A-24.

Effect of SET SORT on LISTPROC and LISTSOURCE A-19
Example A-25. LISTSRLINFO Option (Loadfile) A-19
Example A-26. LISTUNRESOLVED Option (Loadfile) A-20
Example A-27. LISTOPTIMIZE Option (Load fil e) A-21

Contents

nld and noft Manual—520384-003

ix

Examples (continued)

Examples (continued)

Example A-28. Effect of SET SCOPESOURCE on LISTOPTIMIZE Option A-21
Example A-29. Effect of SET SCOPESOURCE on XREFPROC Option A-21
Example A-30. Effect of RESET SCOPESOURCE on XREFPROC Option A-22
Example A-31. XREFPROC Option (Loadfile) A-23
Example A-32. DUMPPROC Option A-24
Example A-33. Effect of SET FORMAT INNERLIST on DUMPPROC Option A-25
Example A-34. LISTSRLFIXUP Option A-26
Example A-35. LISTSRLEXPORTS Option A-27
Example A-36. LISTSRLFIXUP (LLF) Option A-27

Tables

Table 2-1. Using the Guardian nld Utility to Link SRLs 2-17
Table 2-2. Using the OSS nld Utility to Link SRLs 2-19
Table 2-3. Floating-Point Consistency Check by nld Utility

(floattype Not Specified) 2-23

Table 2-4. Floating-Point Type Consistency Check by nld

(floattype Specified) 2-24
Table 2-5. Incompatible Program File and User Library floattypes (TNS) 2-25
Table 2-6. Local and Shared Symbols by Language 2-30
Table 2-7. Declarations and Definitions by Language 2-31
Table 3-1. nld Flag Summary 3-1
Table 3-2. Descriptions of Run-Time Attributes 3-13
Table 3-3. Default Run-Time Attribute Values 3-15
Table 4-1. noft Listing Options 4-4
Table 4-2. noft Dumping Options 4-5
Table 4-3. noft Control Options 4-5
Table 5-1. noft Flag Summary 5-1
Table 7-1. Unnecessary Information in Loadfiles 7-1
Table 8-1. Loadfile Segments and Sections 8-1
Table 8-2. MDEBUG Section Tables 8-2
Table 9-1. Corresponding Binder Tasks and Native Utilities 9-1
Table 9-2. Comparing Binder Commands to nld Options 9-3
Table 9-3. Comparing Binder with noft 9-6
Table 10-1. Comparison of nld Diagnostic Types 10-1
Table 10-2. Warning and Informational Message Defaults 10-1

Contents

nld and noft Manual—520384-003

x

nld and noft Manual—520384-003

xi

What’s New in This Manual

Manua l In forma ti o n

nld and noft Manual

Abstract

This manual explains how to use the following TNS/R native object file utilities: nld
(T6017), which links and changes object file attributes; noft (T9626), which displays
object files; ar (T8629), which creates and maintains archives of object files; and
strip (T8629), which removes unnecessary information from loadable object files
(loadfiles) in the HP NonStop™ Kernel Open System Services (OSS) environment.

Product Version

nld D44
noft D45
ar D43
strip D43

Supported Release Updates (RVUs)

This manual supports D45 and G06 and all subsequent RVUs until otherwise indicated
in a new edition.

Document History

Part Numb er Pub l i sh ed

520384- 003 May 2003

Part Number Product Version Published

426922- 001 nld D44, no ft D4 2, ar D43 November 2000
427686- 001 nld D44, no ft D4 2, ar D43, strip D 43 February 2001
520384- 001 nld D44, no ft D4 2, ar D43, strip D 43 July 2001
520384- 002 nld D44, no ft D4 2, ar D43, strip D 43 February 2002
520384- 003 nld D44, no ft D4 5, ar D43, strip D 43 May 2003

What’s New in This Manual

nld and noft Manual—520384-003

xii

New and Changed Information

New and Changed Information

•

nld Utility on page xii

•

noft Utility on page xii

•

Miscellaneous on page xiii

nld Utility

New information in:

•

Native Object Files on page 1-2

•

nld on page 1-2

•

Running Windows nld on the PC on page 2-4

•

C Programs on page 2-9

•

C++ Programs on page 2-10

•

Table 2-1, Using the Guardian nld Utility to Link SRLs, on page 2-17

•

Table 2-2, Using the OSS nld Utility to Link SRLs, on page 2-19

•

-e on page 3-5

•

Table 3-2, Descriptions of Run-Time Attributes, on page 3-13

•

Table 3-3, Default Run-Time Attribute Values, on page 3-15

•

Fatal Errors on page 10-12:

°

1306

°

1307

•

Nonfatal Errors on page 10-61:

°

2022

°

2041

°

2042

•

Warnings on page 10-69:

°

10043

°

10044

noft Utility

•

Changes to Section 5, noft Options:

°

The option LISTUNRESOLVED or LU on page 5-35 has a new option,
EXCLUDE or E, which excludes system-supplied functions

°

Correction of the syntax of SET on page 5-42

What’s New in This Manual

nld and noft Manual—520384-003

xiii

Miscellaneous

°

The option XREFPROC or XP on page 5-49 can now identify reference
parameters in a non-PIC target file

°

The following examples have been changed or added to reflect support for
Dynamic-Link Libraries (DLLs):

°

Example 5-11, LAYOUT Option, on page 5-21 (changed)

°

Example 5-12, LISTATTRIBUTE Option for Non-PIC Object File, on

page 5-22 (changed)

°

Example 5-13, LISTATTRIBUTE Option for PIC Object File, on page 5-23

(added)

°

Example 5-31, Effect of EXCLUDE on LISTUNRES OLVED Option, on

page 5-37 (changed)

°

Example 5-40, XREFPROC Option for Non-PIC Object File With
“Reference” Indicators (CALLS and DETAIL), on page 5-52 (added)

•

Changes to Section 11, noft Diagnostic Messages:

°

New data errors:

°

1006

°

1007

°

1065

°

Changed data error 1007

°

New warnings:

°

2013

°

2014

°

2015

°

2016

•

In Appendix A, Sample nld and noft Session, the examples have been rerun on the
newest software

Miscellaneous

•

New glossary items:

°

dynamic-link library (DLL)

°

PIC (position-independent code)

°

shared code

•

Changes to Section A, Sample nld and noft Session, indicated by change bars

•

Miscellaneous minor changes, indicated by change bars

What’s New in This Manual

nld and noft Manual—520384-003

xiv

Miscellaneous

nld and noft Manual—520384-003

xv

About This Manual

This manual explains how to use the following TNS/R native object file utilities:

•

nld, which links and changes object file attributes

•

noft, which displays object files

•

ar, which creates and maintains archives of object files

•

strip, which removes unnecessary information from loadable object files
(loadfiles) in the HP NonStop™ Kernel Open System Services (OSS) environment

Subsections:

•

Audience on page xv

•

Related Reading on page xvi

•

Your Comments Invited on page xvi

•

Notation Conventions on page xvii

Audience

This manual is intended for systems programmers and application programmers who
are familiar with the following:

•

HP NonStop™ servers

•

NonStop Kernel operating system

•

Reference manuals a nd pr ogr amme r’s guides for the lan guage s i n which pr ogr ams
are written (C/C++, COBOL, and pTAL—see R elated Readin g on page xvi)

About This Manual

nld and noft Manual—520384-003

xvi

Related Reading

Related Reading

•

C/C++ Programmer’s Guide

•

COBOL85 for NonStop Systems Manual

•

DLL Programmer’s Guide for TNS/R Systems

•

Guardian Procedure Calls Reference Manual

•

Guardian Procedure Errors and Messages Manual

•

Guardian Programmer’s Guide

•

Guardian User’s Guide

•

Inspect Manual

•

ld and rld Reference Manual

•

Open System Services Programmer’s Guide

•

Open System Services User’s Guide

•

Open System Services Shell and Utilities Reference Manual

•

pTAL Conversion Guide

•

pTAL Reference Manual

•

TACL Reference Manual

•

TNS/R Native Application Migration Guide

•

Using the Command-Line Cross Compilers on Windows

Your Comments Invited

After using this manual, please take a moment to send us your comments. You can do
this by:

•

Completing the online Contact NonStop Publications form if you have Internet
access.

•

Faxing or mailing the form, which is included as a separate file in Total Information
Manager (TIM) collections and located at the back of printed manuals. Our fax
number and mailing address are included on the form.

•

Sending an e-mail message to the address included on the form. We will
immediately acknowledge receipt of your message and send you a detailed
response as soon as possible. Be sure to include your name, company name,
address, and phone number in your message. If your comments are specific to a
particular manual, also include the part number and title of the manual.

Many of the improvements you see in manuals are a result of suggestions from our
customers. Please take this opportunity to help us improve future manuals.

About This Manual

nld and noft Manual—520384-003

xvii

Notation Conventions

Notation Conventions

•

Hypertext Links on page xvii

•

General Syntax Notation on page -xvii

•

Example Notation on page xix

•

Change Bar Notation on page xix

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 Sy ntax Notati on

The following list summarizes the notation conventions for syntax presentation in this
manual.

UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words; enter

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

[ ] 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 may 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:

LIGHTS [ ON ]
[ OFF ]
[ SMOOTH [ num ] ]

K [ X | D ] address-1

About This Manual

nld and noft Manual—520384-003

xviii

General Syntax Notation

{ } 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 may 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-1 [ , new-value ]...
[ - ] {0|1|2|3|4|5|6|7|8|9}...

An ellipsis imme diately fol lowing a single syntax item indi cates 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 entered 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 enter 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 the following
example, there are no spaces permitted between the period and any other items:

$process-name.#su-name

About This Manual

nld and noft Manual—520384-003

xix

Example Notation

Line Spaci ng. 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 / ] CONTROLLER
[ , attribute-spec ]...

Example Notation

In examples with user input, user input is in bold type and it is assumed that the user
presses the return key after typing the input. For instance, in the example:

ENTER RUN CODE
?123
CODE RECEIVED: 123.00

the system displays ENTER RUN CODE on one line and prompts the user with ? on the
next line, the user types 123 and presses return, and the system displays:

CODE RECEIVED: 123.00.

Change Bar Notation

A change bar (as shown to the right of this paragraph) indicates a substantive
difference between this edition of the manual and the preceding edition. Change bars
highlight new or revised information.

About This Manual

nld and noft Manual—520384-003

xx

Change Bar Notation

nld and noft Manual—520384-003

1-1

1 Introducti on t o the Ut il itie s

The utilities operate in the TNS/R native mode development environment on TNS/R

native object files. All of the utilities except nld operate on both PIC (position-
independent code) and non-PIC (non-position-independent code) files.

PIC and non-PIC native object files are generated by the native C, native C++, native
COBOL, and pTAL compilers. For information on these compilers, see the following
manuals:

•

C/C++ Programmer’s Guide

•

COBOL85 for NonStop Systems Manual

•

pTAL Reference Manual

For general information about PIC, see the DLL Programmer’s Guide for TNS/R
Systems.

In the TNS/R native development environment, the functions that nld and noft
provide are similar but not identical to the functions that the Binder product provides in
the TNS development environment. For migration information, see Section 9,

Converting From Binder to nld and noft.

Subsections:

•

Native Object Files on page 1-2

•

nld on page 1-2

•

noft on page 1-4

•

ar on page 1-5

•

strip on page 1-5

Utility Full Name Description

nld Native link editor Links one or m ore non-PIC object files to produce a

single non-PIC loadfile

or linkfile.

(To produce a PIC object file—suc h as a dynamic-

link library (D LL)—use the ld utility, which is

explained in the ld and rld Reference Manual.)

noft Native object file tool Displays all portions of native object files
ar Archive tool Creates and maintains archives of files for

processing by nld

strip strip utility Removes unnecessary information from loadfiles

Introduction to the Utilities

nld and noft Manual—520384-003

1-2

Native Objec t Fi les

Native Object Files

nld, noft, ar, and strip operate on native object files. Native object files are in
Executable and Linking Format (ELF), a standard format used for object files, with HP
extensions. For details on the structure of native object files, see Section 8, Native

Object File Structure.

Native object files are either linkfiles or loadfiles, but not both.

The native compilers produce only linkfiles. The nld utility can produce either linkfiles
or loadfiles.

Linkfiles can be used as nld input or noft input.
Loadfiles can be used as nld input in several ways:

•

For change of attributes or stripping options

•

For use in determining the libraries to be used at run time

•

As symbol bindings.
Loadfiles can also be used as noft input.
For example:

nld newobj.o crtlmain.o zcrtlsrl

specifies a linkfile (newobj.o), a library linkfile (crtlmain.o), and a library loadfile
(zcrtlsrl). Including the library load file in the nld command makes its facilities
available at run time.

Native object files in the Guardian environment have a file code of 700.

nld

The nld utility allows you to:

•

Link one or more non-PIC TNS/R native object files to produce a single non-PIC

loadfile or linkfile

•

Modify existing loadfiles
The nld utility runs in the following environments:

•

Guardian

•

OSS

•

Windows NT, Windows 2000, and Windows XP, by means of the HP Enterprise

Toolkit—NonStop Edition (ETK), which is based on Microsoft Visual Studio .NET

Can Be Linked to Produce a Loadfile Can Be Loaded for Execution

Linkfiles Yes No
Loadfiles No Yes

Introduction to the Utilities

nld and noft Manual—520384-003

1-3

nld

The nld utility has the same capabilities in each environment, but each environment
has a slightly different syntax.

You can run nld in the following ways:

•

Directly

•

Automatically, from the following compilers:

•

As a batch process by issuing nld commands from a terminal or a command file
You cannot run nld interactively.
This manual explains only how to run nld directly. For information on running nld

from compilers, see the following manuals:

•

C/C++ Programmer’s Guide

•

COBOL85 for NonStop Systems Manual

•

pTAL Reference Manual

For more information about nld in this manual, see:

•

Section 2, nld Utility

•

Section 3, nld Options

•

Section 10, nld Diagnostic Messages

Environment Compiler T Number

Guardian NMC T9577

NMCPLUS T9225
NMCOBOL T8107

OSS c89 T8164

nmcobol T8107

Window s N T *
Window s 2000*
Window s XP*

All of the ab ov e and ptal T9248

* By means of ETK

Introduction to the Utilities

nld and noft Manual—520384-003

1-4

noft

noft

The noft utility reads and displays information from native object files. noft allows
you to:

•

Determine the optimization level of procedures in a file

•

Display object code with corresponding source code

•

List shared run-time library (SRL) references in an object file

•

List unresolved references in an object file

•

List object file attributes

•

Display the following object file components:

°

Various file headers

°

Program text and data

°

Symbol table and its component parts

°

Run-time procedure table and relocation tables
These noft capabilities are useful when developing and debugging programs.
The noft utility runs in the following environments:

•

Guardian

•

OSS

The noft utility has the same capabilities in each environment, but each environment
has a slightly different syntax.

You can run noft in the following ways:

•

Interactively from the TACL prompt or OSS shell prompt

•

As a batch process by issuing commands from a terminal or a command file

For more information, see:

•

Section 4, noft Utility

•

Section 5, noft Options

•

Section 11, noft Diagnostic Messages

Introduction to the Utilities

nld and noft Manual—520384-003

1-5

ar

ar

The ar utility allows you to:

•

Create archives from groups of files

•

Modify archives by:

°

Adding files

°

Extracting files

°

Deleting files

°

Replacing files
When an archive contains one or more native (TNS/R) files, nld can use that archive

as an object file library. If an archive contains both TNS and TNS/R files, nld cannot
use that archive. If a mixed file is created on a Windows platform, it is not flagged as
erroneous, but only because Windows does not recognize TNS files as object files.

The ar utility runs in the following environments:

•

Guardian

•

Open System Services (OSS)

•

The following PC platforms:

For more information, see:

•

Section 6, ar Utility

•

Section 12, ar Diagnostic Messages

strip

The strip utility removes unnecessary information from loadfiles. Unnecessary
information is that which is not required for proper execution of the files.

The strip utility runs in the Open System Services (OSS) environment.
For more information, see Section 7, strip Utility.

Note. The ar utility ca n also use archives c reated by the ld ut ilit y. For inform at ion about the
ld utility, see the ld and r ld R eference Manual.

Platform

Operating System

Windows 98 Windows NT Windows 2000 Windows XP

TDS

1

Yes Yes No No

ETK

2

No Yes Yes Yes

1. Tandem Development Suite

2. HP Enterprise Toolkit—NonSt op Edition

Introduction to the Utilities

nld and noft Manual—520384-003

1-6

strip

nld and noft Manual—520384-003

2-1

2 nld Utility

The nld utility, the native link editor, links one or more non-PIC TNS/R native object
files to produce a single non-PIC loadfile or linkfile.

Subsections:

•

Running the nld Utility in the Guardian Environment on page 2-1

•

Running the nld Utility in the OSS Environment on page 2-3

•

Running Windows nld on the PC on page 2-4

•

Changing the Target Environment on page 2-8

•

Creating Loadfiles and Linkfiles on page 2-8

•

Linking Programs on page 2-9

•

Linking User Libraries on page 2-13

•

Linking Shared Run-Time Libraries (SRLs) on page 2-15

•

Linking Archive Files on page 2-21

•

Linking Floating-Point Pro gram s on page 2-22

•

Searching for Archives and SRLs With Simple Filenames on page 2-27

•

Dynamic and Static Linking on page 2-28

•

Stripping Symbol Information on page 2-29

•

nld Compilation Rules on page 2-29

Running the nld Utility in the Guardian
Environment

To run the nld utility in the Guardian environment, use the following syntax:

[RUN] NLD

is the TACL command to start the nld process.

[RUN] NLD [ / IN command-Filename [, OUT output-listing ] / ]
[ Filename ] ... [ option ] ...

Note. Filename argument s need not be s pecifi ed bef ore option arguments. Arguments ca n
be mixed. An item that begins with a hyphen (-) is an option, any other item is a Filename.

nld Utility

nld and noft Manual—520384-003

2-2

Running the nld Utility in the Guardian Environment

command-Filename

is a Guardian filename or a map DEFINE for an nld command file. nld uses
command-Filename only if no Filename or option arguments are specified
on the command line; otherwise, nld ignores command-Filename.

output-listing

is a Guardian filename to which nld writes its listing. The file can be type 101 (edit
file) or type 129 (spooler file).

If output-listing is a disk filename and the file does not exist, nld creates a
type 101 edit file.

If you omit the OUT option, nld writes its output to your current default output file.

Filename

is a Guardian filename for a native object file. Depending on the options specified,
the file can be a linkfile or a loadfile.

option

is an nld option (a flag and its parameters, if any). You must include a space
between a flag and its parameters except after the -l and -L flags. Case is not
significant when specifying nld options, except for the -l and -L flags. For
descriptions of nld flags and their parameters, see Section 3, nld Options.

If you do not specify any para meter s on the comm and line and the standard input fil e is
not an edit file, nld returns syntax information.

You can specify input from the command line or use the option -fl or -obey on
page 3-6, which allows the contents of a file to be entered in the command input at the
point specified. Use the -obey option to supply several options or input filenames.

Example 2-1 links together the input object files named objecta and objectb to

create a loadfile named objectc.

Example 2-2 changes the HIGHPIN attribute in the loadfile exeobj to OFF.

Example 2-1. Creating a Loadfile (Guardian)

nld objecta objectb -o objectc

Example 2-2. Changing the HIGHPIN Attribute (Guardian)

nld -change highpin off exeobj

nld Utility

nld and noft Manual—520384-003

2-3

Running the nld Utility in the OSS Environment

Running the nld Utility in the OSS
Environment

To run the nld utility in the OSS environment, use the following syntax:

option

is an nld option (a flag and its parameters, if any). A flag begins with a hyphen (-).
You must include a space between a flag and its parameters except after the -l
and -L flags. Case is not significant when specifying nld options, except for the

-l and -L flags. For descriptions of nld fl ags an d their p arameters, see Section 3,

nld Options.

Filename

is an OSS filename for a TNS/R native object file. The nld utility supports /E OSS
directories. Depending on the flags specified, the object file can be a linkfile or a
loadfile.

You can specify input from the command line or use the option -fl or -obey on
page 3-6, which allows the contents of a file to be entered in the command input at the
point specified. Use the -obey option to supply several options or input filenames.

Example 2-3 combines object files named objecta, objectb, and objectc and

creates a loadfile named objectd.

Example 2-4

links the object files named obj1.o and obj2.o together into a user

library named lib.

Example 2-5

links object files named obj3.o and obj4.o together into a program

named prog. It also associates prog with a user library with the Guardian name

$a.b.c. The backslash prevents the shell from misinterpreting the dollar sign ($).

nld [ option ] ... Filename

Example 2-3. Creating a Loadfile (OSS)

nld objecta objectb objectc -o objectd

Example 2-4. Creating a User Library (OSS)

nld obj1.o obj2.o -ul -o lib

Example 2-5. Creating a Program File (OSS)

nld obj3.o obj4.o -o prog -libname \$a.b.c

nld Utility

nld and noft Manual—520384-003

2-4

Running Windows nld on the PC

Example 2-6 uses the C object files test1.o and test2.o to build a program named

prog. Because the program is a C program, the crtlmain.o library object file is
required. The obey option directs nld to link all of the required SRLs in the program.

Running Windows nld on the PC

Using ETK, you can run Windows nld on:

•

Windows NT 4.0

•

Windows 2000

•

Windows XP
ETK has both a command-line interface and a graphical user interface (GUI).
Subsections:

•

Components of Windows nld on page 2-4

•

Directory Structure of Windows nld on page 2-4

•

Compilers That Can Launch Windows nld on page 2-5

•

How Windows nld Differs from nld on page 2-5

•

How the ETK Command-Line and GUI Interfaces Differ on page 2-6

•

Command-Line Interface Linking Options on page 2-7

Components of Windows nld

The components of Windows nld are:

Directory Structure of Windows nld

The directory structure of Windows nld is:

Example 2-6. Creating an Executable C Program (OSS)

nld /user/lib/crtlmain.o test1.o test2.o \

-obey /usr/lib/libc.obey -o prog

Component Description

nld.dll A Windows dy namic-link library (DLL ) th at im plements nld functionality
nld.exe A Windows ex ecutable file th at provides a dire c t co m m and line interfac e

for nld functionality

Directory Files

bin nld.exe
cmplr nld.dll
lib SRLs for linking

nld Utility

nld and noft Manual—520384-003

2-5

Compilers That Can Launch Windows nld

Compilers Tha t Can Launch Windows nld

Windows nld is a component of these Windows-based cross-compilers, which can
launch it automatically after compilation:

When a compiler launches Windows nld, the compiler driver selects the correct run­time libraries.

The command in Example 2-7 on page 2-5 runs the native COBOL85 co mpiler,
nmcobol, compiling the source files text3.cob and text4.cob, and then launches
Windows nld, producing the executable file pcoss.exe for the OSS environment.

How Windows nld Differs from nld

Windows nld object files are compatible with NonStop Kernel object files; that is, you
can build object files on either of these platforms and then link them on the other.

Linking object files on Windows nld is usually much faster than linking them on the
NonStop Kernel.

For Windows nld, the following flags are meaningless:

•

-NS_extent_size on page 3-10

•

-NS_max_extents on page 3-10

Note. On the PC, you must use -l or -lib on page 3-7 on th e c om m and line to sp ec if y the
location for nld to look for SRLs and archives; there are no standard library locations.

Compiler Compiler Driver DLL

Native C/C++ c89.dll
Native COBOL coboldvr.dll
pTAL ptaldvr.dll

Example 2-7. Running nmcobol and Launching Windows nld

nmcobol text3.cob text4.cob -Wsystype=oss -o pcoss.exe

nld Utility

nld and noft Manual—520384-003

2-6

How the ETK Command-Line and GUI Interfaces

Differ

How the ETK Command-Line and GUI Interfaces Differ

Command-Line Interface GUI

Software
Requirements

You need only ins ta ll one of the

Compi lers Tha t Ca n Launch
Windows nld on page 2-5

You must install all of the following:

•

One of th e Compilers That

Can Launch Windo w s n ld on

page 2-5

•

Microsof t Visual Studio .NET

•

The ETK package

Where
Instructions
Are

Using the Command-Line Cross
Compilers on Windows on the

compiler’s CD

Online he lp

Run-Time
Libraries

You must specify them You must specify them

Filename Path
Format

NonStop Kernel format (see the

Guardian U s er’s Guide or the
Open Sys te m Services User’s
Guide)

Window s format (see th e
documentation for your Windows
operating system)*

pTAL You must compile and link a

program in s eparate steps

You can com pile and link a
prog ram in one step

* A Windows format filename path that includ es a backslash (\) or a space must be enclosed in quotation ma rks
(as in Example 2-8

on page 2-6)

Example 2-8. Running nld from the Command Prompt

nld test1.o test2.o "c:\Program Files\Compaq ETK-NSE\g06.15\lib\crtlmain.o"

-set systype oss -set highpin on -set highrequester on -set inspect on -set
runnamed on -verbose -L "c:\Program Files\Compaq ETK-NSE\g06.15\lib" -obey
"Program Files\Compaq ETK-NSE\g06.15\lib\libc.obey" -o mystest.exe

nld Utility

nld and noft Manual—520384-003

2-7

Command-Line Interface Linking Options

Command-Line Interface Linking Options

The command-line interface link options for C/C++ and COBOL are:

•

-l=library

•

-L=directory

•

-s

•

-Wansistreams

•

-WBdynamic

•

-WBstatic

•

-Wheap=N[b|w|p]

•

-Whighpin={on|off}

•

-Whighrequesters={on|off}

•

-W[no]inspect

•

-Wnld="arguments"

•

-Wnld_obey file

•

-Wnostdlib

•

-Wr

•

-Wrunnamed

•

-W[no]saveabend

•

-Wx

nld Utility

nld and noft Manual—520384-003

2-8

Changing the Target Environment

Changing the Target Environment

The target environment is the environment in which you intend to run the program file.
By default, the Guardian version of nld builds files intended to run in the Guardian
environment and the OSS version of nld builds files intended to run in the OSS
environment.

To build a program file intended to run in the Guardian environment using the OSS
version of nld, specify:

-set systype guardian

To build a program file intended to run in the OSS environment using the Guardian
versions of nld, specify:

-set systype oss

Example 2-9, in the O SS environment, links the object files names obj6.o and

obj7.o into a program named prog that you intend to run as a Guardian process.

Creating Loadfiles and Linkfiles

A loadfile cannot be linked to a new object file, it can be used only as input to nld with
options that modify an existing loadfile. A linkfile can be used as nld input again.

nld creates a loadfile if you do not specify the -r flag. If you do specify the -r flag,
nld creates a linkfile.

Note. In some cases, such as when C/C++ programs include stdio.h, setting the targe t
environment with the -set systype option might result in a program that executes incorrectly
in the specified environment. In such cases, you must specify the systype option on th e
compiler co m m and line to ens ure the correct c ode is created.

Example 2-9. Creating a Program for the Guardian Environment (OSS)

nld obj6.o obj7.o -o prog -set systype guardian

nld Utility

nld and noft Manual—520384-003

2-9

Linking Programs

Linking Programs

•

C Programs on page 2-9

•

C++ Programs on page 2-10

•

COBOL Programs on page 2-12

•

pTAL Programs on page 2-13

•

Mixed-Language Programs on page 2-13

•

Programs With Embedded NonStop SQL/MP on page 2-13

C Programs

C programs require access to their run-time environments. To create an executable C
program, you must link to the run-time environment initialization code and the shared
run-time libraries (SRLs) your program uses. The NMC and c89 compilers
automatically link to the required items. If you use nld directly to link a C program, you
must specify these items in nld options.

Follow these step to create an executable C program using nld:

1. Link together the object code files that you compiled.

2. Link to the C run-time library initialization object code file:

3. Link to the SRLs that your program uses. To link the standard set of C SRLs, use

the following options:

4. If your program uses active backup programming functions, such as

__ns_start_backup(), link to the active backup programming support object

code file:

Note. You can only link linkf iles into a program. You cannot link loadfi les, or a combination of
loadfiles and linkfile s, into a pr ogram.

Environment Run-Time Library Initialization Object Code File

Guardian $SYSTEM.SYSTEM.CRTLMAIN
OSS /usr/lib/crtlmain.o

Environment Option for Linking the Standard Set of C SRLs

Guardian -OBEY $SYSTEM.SYSTEM.LIBCOBEY
OSS

-obey /usr/lib/libc.obey

Environment Active Backup Programming Support Object Code File

Guardian $SYSTEM.SYSTEM.CRTLNS
OSS /usr/lib/crtlns.o

nld Utility

nld and noft Manual—520384-003

2-10

C++ Programs

5. If you want to overload the new and delete operations, you must link these files

to your program:

For information about active backup programming in C, see the Guardian

Programmer’s Guide.

Example 2-10 takes a C source program named MYSRC, compiles it into an object file

named MYOBJ, and creates a loadfile named MYEXEC. It links to the C run-time library
initialization object file named CRTLMAIN and the SRLs named ZCRESRL and
ZCRTLSRL. In the Guardian environment, ZCRESRL and ZCRTLSRL are located in the
active SYSnn subvolume.

C++ Programs

There are three versions of C++:

When you compile a C++ program, you can specify its version with the command-line
directive VERSION1, VERSION2, or VERSION3. The default is VERSION3.

Environment Active Backup Programming Support Object Code File

Guardian $SYSTEM.SYSTEM.CPPINIT
OSS /usr/lib/cppinit.o

Example 2-10. Creating an Executable C Program
Guardian Environment

NLD $SYSTEM.SYSTEM.CRTLMAIN MYOBJ -o MYEXEC &

-l ZCRESRL -l ZCRTLSRL

OSS Environment

nld /usr/lib/crtlmain.o myobj -o myexec -l zcresrl -l zcrtlsrl

Version

Conforms to ANSI and
ISO Standards for C++ Supports PIC (position-independent code)

1No No
2No Yes
3 (default ) Yes Yes

nld Utility

nld and noft Manual—520384-003

2-11

C++ Programs

The version, known as the C++ Dialect, is stored in one of the program's internal
structures. To see a program’s C++ dialect, use the noft option LISTATTRIBUTE or LA
on page 5-22.

Mixing versions of C++ in a loadfile is not recommended (except for mixing
CPP_NEUTRAL with one other version). The result is either a nonfatal error or a
warning, depending on the combination:

For information about nonfatal errors and warnings, see Nonfatal Er ror s on page 10-61
and Warnings on page 10-69.

C++ programs require access to their run-time environments. To create an executable
C++ program, you must link to the run-time environment initialization code and the
shared run-time libraries (SRLs) your program uses. The NMC and c89 compilers
automatically link to the required items. If you use nld directly to link a C++ program,
you must specify these items in nld options. For details, see the C/C++ Programmer’s
Guide.

Follow these step to create an executable C++ program using nld:

1. Link together the object code files that you compiled.

2. Link to the C++ run-time library initialization object code file:

C++ Input Files C++ Version Recorded in the Loadfile*

VERSION1 CPP_V1 (1)
VERSION2 CPP_V2 (2)
VERSION3 CPP_V3 (3)
Mixed versions Lowest version

*

When none of the input files are C++ fi les, the value CPP_NEUTRAL is recorded in the loadfile.

LINKFILE

CPP_NEUTRAL CPP_V1 CPP_V2 CPP_V3

L
I
N
K
F
I
L
E

CPP_NEUTRAL Loadfile is

CPP_NEUTRAL

Loadfile is
CPP_V1

Loadfile is
CPP_V2

Loadfile is
CPP_V3

CPP_V1 Loadfi le is

CPP_V1

Loadfile is
CPP_V1

Warning
Loadfile is

CPP_V1

Nonfatal
error

CPP_V2 Loadfi le is

CPP_V2

Warning
Loadfile is

CPP_V1

Loadfile is
CPP_V2

Nonfatal
error

CPP_V3 Loadfi le is

CPP_V3

Nonfatal
error

Nonfatal
error

Loadfile is
CPP_V3

Environment Run-Time Library Initialization Object Code File

Guardian $SYSTEM.SYSTEM.CRTLMAIN
OSS /usr/lib/crtlmain.o

nld Utility

nld and noft Manual—520384-003

2-12

COBOL Programs

3. Link to the SRLs that your program uses. To link the standard set of C SRLs, use

the following options:

C++ programs require additional SRLs. See Determining Which SRLs Programs

Require on page 2-17.

4. If your program uses active backup programming functions, such as

__ns_start_backup(), link to the active backup programming support object

code file:

For information about active backup programming in C++, see the Guardian

Programmer’s Guide.

5. If you want to overload the new and delete operations, you must link these files

to your program:

COBOL Programs

In the OSS environment, the nmcobol compiler automatically calls nld to link the
compiled program unless the compiler is run with the -c (compile only) directive.

In the Guardian environment, the NMCOBOL compiler automatically calls nld to link
the compiled program only if the compiler is run with the RUNNABLE directive.

When the NMCOBOL compiler automatically calls nld to link the compiled program, it
gives nld the following:

•

The compiled program’s object filename (either the object filename that you

specified or the default name a.out) as the input filename

•

The name of the COBOL run-time library, ZCOBSRL

•

The name of the common run-time environment library, ZCRESRL

•

Any files located by the SEARCH directive
If you use nld directly to link a COBOL program, you must supply the libraries

ZCOBSRL and ZCRESRL.

Environment Option for Linking the Standard Set of C SRLs

Guardian -OBEY $SYSTEM.SYSTEM.LIBCOBEY
OSS

-obey /usr/lib/libc.obey

Environment Active Backup Programming Support Object Code File

Guardian $SYSTEM.SYSTEM.CRTLNS
OSS /usr/lib/crtlns.o

Environment Active Backup Programming Support Object Code File

Guardian $SYSTEM.SYSTEM.CPPINIT
OSS /usr/lib/cppinit.o

nld Utility

nld and noft Manual—520384-003

2-13

pTAL Programs

pTAL Programs

Because pTAL does not support embedded NonStop SQL/MP or a language-specific
run-time library, there are no special requirements for linking pTAL programs.

Mixed-Language Programs

You can create mixed-language programs containing native C modules, native C++
modules, native COBOL modules, and pTAL modules. The MAIN procedure in a
mixed-language program can be written in C/C++ or COBOL but not pTAL. Mixed­language programs that include C/C++ modules require you to link to the same run­time initialization code and SRLs that C or C++ programs do (see C++ Programs on
page 2-10). Mixed-language progr ams tha t incl ude COBO L mod ules req uire you to link
to the same run-time libraries that COBOL programs do (see COBOL Programs on
page 2-12).

Programs With Embedded NonStop SQL/MP

Native C and native COBOL programs can contain embedded NonStop™ SQL/MP
statements. You can use nld to create a single loadfile from multiple C or COBOL
object files that contain embedded NonStop™ SQL/MP statements. After creating a
loadfile with nld, use the NonStop™ SQL/MP compiler, SQLCOMP, to set up an
executable NonStop™ SQL/MP application.

Always run nld before SQLCOMP. Do not run SQLCOMP on a linkfile and use the
resulting file as nld input.

A user library cannot contain embedded NonStop™ SQL/MP.

Linking User Libraries

A user library, which is optional, is a set of procedures that the operating system can
link to a program file at run time. Putting commonly used procedures in a user library
provides these benefits:

•

Reduces the storage required for object code on disk and in main memory

•

Shares a set of common procedures among applications
The first time you execute a program file after compilation, duplication, or change to

the -libname specification, the operating system searches the user library to resolve
each unresolved external reference before searching the system code and library.

The operating system resolves an external reference by changing the call in the
program file to point to the user library or to the system library. You can then run the
program file repeatedly (using the same -libname specification) without resolving the
reference again.

nld Utility

nld and noft Manual—520384-003

2-14

Linking User Libraries

If the operating system cannot find a user library or system library procedure to satisfy
a run-time external reference, it displays a message as the process starts. When the
process calls an unresolved procedure, the process changes the call to the unresolved
procedure into a call to the Debug utility or the Inspect symbolic debugger, and the
process enters the debug state.

In the TNS environment, either or both the program file and the user library can be
processed by the Accelerator. TNS user libraries can contain embedded NonStop™
SQL/MP statements.

In the TNS/R environment, both the program file and the user library must be compiled
with TNS/R native compilers. TNS/R native user libraries cannot contain embedded
NonStop™ SQL/MP statements. Move procedures with embedded NonStop™
SQL/MP statements to user code before migrating a TNS user library to a TNS/R
native user library. (For more information on migrating TNS user libraries to TNS/R
native user libraries, see the TNS/R Native Application Migration Guide.)

A TNS/R native user library can contain its own data, which is allocated for each
process, in a separate location from the client program’s data. A TNS/R native user
library can call functions in shared run-time libraries (SRLs), such as the C run-time
library. If a user library calls functions in an SRL, you must specify the SRLs when
linking. Do not link the CRTLMAIN object file to a user library.

To create a TNS/R native user library, follow these steps:

1. Compile the procedures that you want to put in the library.

2. Use nld to link the resulting object files into a single executable user library.

Use the -o option to specify the name of the resulting object file.

Use the -ul option to specify that the resulting object file is a user library.

For example, in the Guardian environment, the following command links the object

files file1 and file2 into an executable user library named lib:

nld file1 file2 -o lib -ul

The following command is the OSS equivalent of the preceding command:

nld file1.o file2.o -o lib -ul

If the procedures are written in ... Compile them ...

C or C++ With the SRL pragma and

without the RUNNABLE pragma
COBOL85 Without th e RUNNABLE directive
pTAL With the SRL pragma

Note. You can only link lin k fi les int o a user library. You ca nnot link loadfiles, or a
combin at ion of loadfile s and linkfile s, into a user library.

nld Utility

nld and noft Manual—520384-003

2-15

Linking Shared Run-Time Libraries (SRLs)

A program file can have at most one TNS/R native user library associated with it. The
following table shows how to associate a TNS/R native user library with a program file.

When using programs or user libraries that contain C++ code, it is recommended that
you use the noft option LISTATTRIBUTE or LA on page 5-22 to verify that the program
and the user librar y have comp at ibl e C++ dialects. (For informa tion about C++ dialects,
see C++ Programs on page 2-10.)

User libraries specified at run time override those specified at link time.

Linking Shared Run-Time Libraries (SRLs)

An SRL contains code present in virtual memory at run time, to be shared by other
processes, rather than being copied into object files. An SRL can also contain global
data, and each process using the SRL automatically gets its own run-time copy of the
data, called instance data. A process can use several SRLs.

Some of the code configured in the system library for TNS processes is packaged in
SRLs for native processes, for example:

•

C run-time library

•

TCP/IP sockets library

•

Tools.h++ class library

•

Much of the OSS API

HP supplies public SRLs; you cannot create your own. You can create your own user
library. See Linking User Libraries on page 2-13 for details.

When How

Link time* nld utility -libname library opt ion

nld utility -set libname library op tio n
nld utility -change libname library options

Native c89 utility -Wnld= "nld-options" option
Native nmcobol utility -Wnld= " nld-options" option

Run time TACL command interpreter RUN command LIB option

OSS run command -lib option
OSS runv comm and -lib option
OSS run gtacl command -lib option

* library must be a Guardian file name. For details, see -libname on page 3-9.

Note. nld supports TNS / R nat ive S R Ls. It does not support th e T N S SRL available to TNS
and acce lerat ed programs in the OSS environm ent. See the Binder Manual for details.

nld Utility

nld and noft Manual—520384-003

2-16

Specifying SRLs

In the Guardian environment, each processor loads public SRLs at startup time from
the active SYSnn subvolume. The SYSnn subvolume, located on $SYSTEM, contains a
version of the operating system image for a particular node. A node can have more
than one SYSnn subvolume, but only one active (running) SYSnn subvolume. D42 and
later product versions of nld automatically select the active SYSnn subvolume.
Previous versions of nld required you to specify the active SYSnn subvolume. (To
determine the SYSnn subvolume active on a particular node, use the Guardian
command STATUS 0,0.)

When you use nld to build a program file, nld fixes up references to the SRLs that
you have specified. You can also use nld to repeat the fix-up process on an existing
program to use a new version of an SRL or let the operating system update the
references when you execute the program.

The SRLs required to create a program file depend on the run-time resources a
program uses.

Subsections:

•

Specifying SRLs on pa ge 2-16

•

Determining Which SRLs Programs Require on page 2-17

Specifying SRLs

You can specify SRLs on the nld command line directly and with the options -l or -lib
on page 3-7. Using options is usually easier to understand and more flexible. A file
specified in a -l or -lib option must be an SRL or an archive.

In the Guardian environment, an SRL often has a filename that starts with Z and ends
with SRL, such as ZCOBSRL.

In the OSS environment, an SRL often has a filename that starts with lib and ends
with the filename suffix .srl, such as libc.srl.

nld uses SRLs to resolve undefined symbols after all object files and archive files
specified on the command line have been used. nld uses SRLs in the order specified
on the command line and in -l or -lib options.

You can specify the Guardian subvolumes or OSS directories where nld searches for
SRLs with the option -L or -libvol on page 3-8.

The -bdynamic and -bstatic flags determine if nld performs dynamic or static
linking, respectively. See Dynamic and Static Linking on page 2-28 for details.

nld Utility

nld and noft Manual—520384-003

2-17

Determining Which SRLs Programs Require

Determ ining Which SRLs Programs Require

The SRLs that a program requires depend on:

•

The run-time libraries that the program uses

•

The environment in which the program runs

The nld options that you must specify to link the SRLs that your program requires
depend on:

•

The SRLs that the program requires

•

The environment in which you are using the nld utility

Table 2-1 on page 2-17 and Table 2-2 on page 2-19 apply only to the most common

SRLs, which are:

•

C run-time library

•

C++ run-time library

•

COBOL run-time library

•

Tools.h++ library

•

TCP/IP sockets library

Your program might require additional SRLs for other run-time libraries and services.

Environment in Which You Are Using nld See ...

Guardian Table 2-1

on page 2-17

OSS Table 2-2

on page 2-19

Table 2-1. Using the Guardian nld Utility to Link SRLs (page 1 of 2)

Library That
Program Uses

Environment
in Which
Program
Runs nld Options to Specify

C run-time
library

Guardian -OBEY $SYSTEM.SYSTEM.LIBCOBEY

or

-l ZCRT LSR L -l ZCR ES RL

OSS -OBEY $SYSTEM.SYSTEM.LIBCOBEY

or

-l ZCRT LSR L -l ZCR ES RL -l ZOSS KS RL

-l ZOSS FSR L -l ZSE CS RL -l ZI18 NS RL

-l ZICN VSR L -l ZOS SE SR L -l ZI NE TS RL

-l ZOSS HSR L -l ZST FN SR L

nld Utility

nld and noft Manual—520384-003

2-18

Determining Which SRLs Programs Require

C++ run-time
library

Guardian -l ZCPLSRL -l ZRWSLSRL

-OBEY $SYSTEM.SYSTEM.LIBCOBEY

or

-l ZRWSLSRL -l ZCPLSRL -l ZCRTLSRL

-l ZCRE SRL

OSS -OBEY $SYSTEM.SYSTEM.LIBCOBEY

-l ZOSS HSR L -l ZST FN SR L -l ZC PL SR L

-l ZRWS LSR L

or

-l ZRWSLSRL -l ZCPLSRL -l ZCRTLSRL

-l ZCRESRL -l ZOSSKSRL -l ZOSSFSRL

-l ZSECSRL -l ZI18NSRL -l ZICNVSRL

-l ZOSS ESR L -l ZIN ET SR L -l ZO SS HS RL

-l ZSTF NSR L

VERSION2
S tandard C++
library,
Tools.h++
library
(version 7)

Guardian -OBEY $SYSTEM.SYSTEM.LIBCOBEY

-l ZTLHSRL -l ZRWSLSRL -l ZCPLSRL

or

-l ZCRT LSR L -l ZCR ES RL -l ZCPL SR L

-l ZTLHSRL -l ZRWSLSRL

OSS -OBEY $SYSTEM.SYSTEM.LIBCOBEY

-l ZOSS HSR L -l ZST FN SR L

-l ZCPL SRL -l ZRW SL SR L -l ZT LH SR L

or

-l ZOSS HSR L -l ZCR TL SR L -l ZC RE SR L

-l ZOSS KSR L -l ZOS SF SR L -l ZS EC SR L

-l ZI18 NSR L -l ZIC NV SR L -l ZO SS ES RL

-l ZINE TSR L -l ZST FN SR L -l ZC PL SR L

-l ZRWS LSR L -l ZTL HS RL

VERSION3
S tandard C++
library

Either -l ZS TL SRL

-OBEY $SYSTEM.SYSTEM.LIBCOBEY

COBOL run­time librar ies

Either -l ZC OB SRL -l ZCR ES RL

OSS nlist()
function

OSS -l ZUTILSR L a nd other SRLs required by th e program

environment

TCP/IP socket
library

Either -l ZI NE TSR L and other SR Ls required by th e program

environment

Table 2-1. Using the Guardian nld Utility to Link SRLs (page 2 of 2)

Library That
Program Uses

Environment
in Which
Program
Runs nld Options to Specify

nld Utility

nld and noft Manual—520384-003

2-19

Determining Which SRLs Programs Require

For example, the following nld command links a Guardian C++ program that uses the
Tools h++ class libraries:

NLD $SYSTEM.SYSTEM.CRTLMAIN MYOBJ -o MYEXEC &

-l ZCRESRL -l ZCRTLSRL -l ZCPLGSRL -l ZTLHGSRL -l ZRWSLSRL

CRTLMAIN is the C run-time library initialization object file that contains code required
by all C and C++ programs.

Table 2-2 identifies the OSS nld options required to link the SRLs necessary to create

a program file.

Table 2-2. Using the OSS nld Utility to Link SRLs (page 1 of 2)

Library That
Program
Uses

Environment
in Which
Program
Runs nld Options to Specify

C run-time
library

Guardian -obe y /u sr/ li b/ li bc .o be y

or

-l ZCRTLSRL -l ZCRESRL

OSS -obey /u sr/ li b/ li bc .o be y

or

-l ZCRTL SRL -l ZC RE SR L -l ZO SS KS RL

-l ZOSSF SRL -l ZS EC SR L -l ZI 18 NS RL

-l ZICNVSRL -l ZOSSESRL -l ZINETSRL

-l ZOSSHSRL -l ZSTFNSRL

C++ run-time
library

Guardian -obe y /u sr/ li b/ li bc .o be y

-l ZRWSLSRL -l ZCPLGSRL

or

-l ZRWSLSRL -l ZCRTLSRL -l ZCRESRL

-l ZCPLGSRL

OSS -obey /u sr/ li b/ li bc .o be y

-l ZRWSL SRL -l ZC PL SR L -l ZO SS HS RL

-l ZSTFNSRL

or

-l ZRWSL SRL -l ZC PL SR L -l ZC RT LS RL

-l ZCRES RL -l ZOS SK SR L -l ZO SS FS RL

-l ZSECS RL -l ZI1 8N SR L -l ZI CN VS RL

-l ZOSSESRL -l ZINETSRL -l ZOSSHSRL

-l ZSTFNSRL

nld Utility

nld and noft Manual—520384-003

2-20

Determining Which SRLs Programs Require

The OSS nld utility processes the simple names in the -l options as files within the
Guardian file system. For example, the following nld command links an OSS C++
program that uses the Tools h++ class libraries:

nld myobj.o /usr/lib/crtlmain.o -o myexec -l ZCRESRL

-l ZRWSLSRL -l ZCPLGSRL -l ZTLHGSRL
crtlmain is the C run-time library initialization object file that contains code required

by all C and C++ programs.
The value of the COMP_ROOT environment variable is added to the beginning of the

/usr/lib. By default, the value of COMP_ROOT in the OSS environment is null.

VERSION2
S tanda rd C++
library,
Tools.h++
library
(version 7)

Guardian -obe y /u sr/ li b/ li bc .o be y

-l ZTLHS RL -l ZRW SL SR L -l ZC PL SR L

or

-l ZTLHS RL -l ZRW SL SR L -l ZC PL SR L

-l ZCRTLSRL -l ZCRESRL

OSS -obey /u sr/ li b/ li bc .o be y

-l ZTLHS RL -l ZRW SL SR L -l ZC PL SR L

or

-l ZTLHS RL -l ZRW SL SR L -l ZC PL SR L

-l ZOSSHSRL -l ZCRTLSRL -l ZCRESRL

-l ZOSSKSRL -l ZOSSFSRL -l ZSECSRL

-l ZI18NSRL -l ZICNVSRL -l ZOSSESRL

-l ZINETSRL -l ZSTFNSRL

VERSION3
S tanda rd C++
library

Either -obey /u sr/ li b/ li bc .o be y

-l ZSTLSRL

COBOL run­time librar ies

Either -l ZCOBSRL -l ZCRESRL

OSS
nlist()
function

OSS -l ZUTILSRL and other SRLs required by the program

environment

TCP/IP
socket library

Either -l ZINETSRL and other SRLs required by the program

environment

Table 2-2. Using the OSS nld Utility to Link SRLs (page 2 of 2)

Library That
Program
Uses

Environment
in Which
Program
Runs nld Options to Specify

nld Utility

nld and noft Manual—520384-003

2-21

Linking Archive Files

Linking Archive Files

The nld utility support s arch ive files for select ing input o bject files when bu ilding a new
object file. An archive file is created by the ar utility and contains a collection of object
files. Any type of file can be put into an archive, but nld uses only the relinkable
TNS/R native object files in an archive file.

To create an archive file, you can use the ar utility in either the Guardian environment,
the OSS environment, or on platforms running Windows. The nld utility supports
archive files existing in the Guardian and OSS environments, regardless of where the
archives were created. The ar utility is described in Section 6, ar Utility.

In the OSS environment, archive files often have filenames that start with lib and end
with the filename suffix .a, such as libc.a.

You can specify archive files on the nld command line directly and with the options -l

or -lib on page 3-7. Specifying archive files with options is usually easier to understand

than specifying archive files on the command line.
nld resolves references using archive files in the order they are specified, either on

the command line directly or with -l or -lib options.
nld searches an archive file to resolve references. When nld finds object files that

satisfy references, it copies them from the archive file to the target object file. Unlike
Binder, nld copies the entire object file, not only the individual procedure.

For example, given object files obja, objb, and objc and archive files arc1 and

arc2 and the following nld command line:
nld obja objb -lib arc1 objc arc2 -o myexec

nld performs the following steps:

1. Copies obja and objb.

2. Searches arc1 fo r unresol ved r efere nces in obja and objb. F or those refer ences
satisfied in arc1, nld copies the object file satisfying the reference.

3. Copies objc.

4. Searches arc2 for unresolved references in obja, objb, and objc. nld also
searches arc2 for unresolved references in object files copied from arc1.

A duplicate reference in an object file or an archive file is an error.

nld Utility

nld and noft Manual—520384-003

2-22

Linking Floating-Point Programs

Unlike libraries, which must be specified only once in a linking operation, you might
need to specify archives more than once in the same linking operation. For example, if
the object program obj calls functions fun1 and fun3, and if archive ar1 contains
functions fun1 an d fun2 in sep ar ate ar chives or o bject fi les, an d arch ive ar2 contai ns
function fun3, which calls fun2, then the command:

nld obj.o -l ar1.a -l ar2.a

links obj, ar1 and ar2. nld resolves references to fun1 and fun3, but fun2 is
unresolved.

The following command:

nld obj.o -l ar1.a -l ar2.a -l ar1.a
links obj, ar1 and ar2 completely and nld resolves all references.

Linking Floating-Poi nt Programs

When linking object files using the nld utility, you can specify the floating-point type of
the output object file using the option -set on page 3-13 with the attribute-name
FLOATTYPE. The floating-point type can be any of the following:

•

TANDEM_FLOAT

•

IEEE_FLOAT

•

NEUTRAL_FLOAT

If you do not specify the floating-point type of the output object file, nld derives it from
the types of the input files (see Link-Time Consistency Checking on page 2-23).

When modifying an existing object file, nld sets the type as specified by the option

-change on page 3-4.

Subsections:

•

Link-Time Consistency Checking on page 2-23

•

Run-Time Consistency Checking on page 2-25

•

Linking Mixed-Language Pro gram s on page 2-26

For more information about using IEEE floating-point format:

Topic Document

Buil din g p rog ra ms us in g I EE E fl oati n g-p oi nt
format

Guardi an Progr am m er’s Guide

Operating mode routines
Routine s for converti ng between Tandem
and IEEE f loating-point fo rm ats

Guardian Procedure Calls Reference Manual

Descriptions of the IEEE_FLOAT and
TANDEM_FLOAT pragmas

C/C++ Programmer’s Guide

nld Utility

nld and noft Manual—520384-003

2-23

Link-Time Consistency Checking

Link-Time Consistency Checking

The nld utility checks the consistency of floating-point type combinations when linking
object files. The type of checking depends on whether the floattype attribute is
specified.

•

floattype Not Specified on page 2-23

•

floattype Specified on page 2-24

floattype Not Specified

When the floattype attribute is not explicitly set with the -set option, nld uses the
floattype attribute values of all the input object files to determine the floattype

attribute value of the out put obje c t file. If the consisten cy checks of th e input o bject files
result in an invalid floating-point type or an inconsistent value, nld issues an error
message and does not create an output object file.

Table 2-3. Floating-Point Consistency Check by nld Utility
(floattype Not Specified)

Number of Input Files With

Floating-Point Type ... Consistency Check Result

Tandem IEEE Neutral

Error Message
Issued

Floating-Point type
of Output File

1 or more 0 0 or more No TANDEM_FLOAT
0 1 or more 0 or more No IEEE_FLOAT
0 0 1 or more No NEUTRAL_FLOAT
1 or more 1 or more 0 or more Yes No output object file is created

nld Utility

nld and noft Manual—520384-003

2-24

Link-Time Consistency Checking

floattype Specified

When the floattype attribute is explicitly specified with the -set option, any
combination of floating types is allowed—nld sets the floattype attribute value for
the output object file to the specified value. If nld detects an inconsistency between
the specified floattype attribute value and that of any input object file, it issues a
warning message. Table2-4 summarizes this paragraph.

Table 2-4. Floating-Point Type Consistency Check by nld (floattype Specified)

Number of Input Files With
Floating-Point Type ... Consistency Check Result With floattype Set to ...

Tandem IEEE Neutral Tandem IEEE Neutral

1 or
more

00 or

more

No message.
Output file is
TANDEM_FLOAT.

Warning
message. Output
file is
IEEE_FLOAT.

Warning mess age.
Output file is
NEUTRAL_FLOAT.

01 or

more

0 or
more

Warning
message. Output
file is
TANDEM_FLOAT.

No message.
Output file is
IEEE_FLOAT.

Warning mess age.
Output file is
NEUTRAL_FLOAT.

0 0 1 or

more

Warning
message. Output
file is
TANDEM_FLOAT.

Warning
message. Output
file is
IEEE_FLOAT.

No message.
Output file is
NEUTRAL_FLOAT.

1 or
more

1 or
more

0 or
more

Warning
message. Output
file is
TANDEM_FLOAT.

Warning
message. Output
file is
IEEE_FLOAT.

Warning mess age.
Output file is
NEUTRAL_FLOAT.

Note. If source code manipulates floating-point data, either the TANDEM_FLOAT or the
IEEE_FLOAT ma c hine instruct ion is placed int o t he object code, de pending on the compiler

directive (pragm a) floattype. The nld option -set floattype cannot change the
instruction set. To change the instruction set, you must recompile the source code with the
correct directive (pragma). The two cases where you use the nld option -set floattype
are:

•

The floattype in a module has been set to either TANDEM_FLOAT or IEEE_FLOAT, but
the mod ule does no floa t ing-point operat ions. You want to link the m odule to another
module t hat does float ing-point operations, but the othe r m odule has a dif feren t floattype
value.

•

A program deliberately uses both types of floating-point instructions.

nld Utility

nld and noft Manual—520384-003

2-25

Run-Time Consistency Checking

Run-Time Consistency Checking

If a program tries to use a processor that does not support IEEE floating-point format,
then process creati on e rro r code 64 occu rs (IEEE floating-point support not
available on this processor). To determine whether a processor can run IEEE
floating-point instructions, programs can call the PROCESSOR_GETINFOLIST_
procedure. For more information about this procedure, see the Guardian Procedure
Calls Reference Manual.

Run-time consistency checking includes a check for floattype consistency between
the program file and the user library file, if one i s used. IE EE and Tandem floating-point
formats use different data formats and calling conventions: IEEE floating-point values
are typically passed in IEEE floating-point registers, while Tandem floating-point values
are passed in general purpose registers. Problems can occur if a function using one
floating-point format calls a function using the other format. Checks are performed at
process creation to ensure that the user library (if there is one) has a floattype
compatible with that of the program file. If not, the program is not allowed to run.

If the floattype attribute of the program file is IEEE and floattype attribute of the
user library file is Neutral, the program is allowed to run, and the C/C++ run-time
libraries operate in IEEE mode.

Even if the user library is marked with a floattype attribute that conflicts with the
program file, the program can use the library if the program does not call anything in
the user library that uses floating point. In this case, you must mark the program file
with the -set float_lib_overrule on command to disregard the floattype
attribute of the user library file (see Overruling the Run-Time Consistency Check on
page 2-26).

TNS/R Native User Libraries

If you are using a TNS/R native user library, the library file must use the same floating­point format as the program, and the library must be marked accordingly. If the user
library does not use floating point at all, you can mark the library NEUTRAL_FLOAT
using the -set floattype or -change floattype option. Then the user library
can be used by any kind of program.

Table 2-5. Incompatible Program File and User Library floattypes (TNS)

floattype in program file floattype in user library file

IEEE Tandem
Tandem IEEE
Neutral IEEE

nld Utility

nld and noft Manual—520384-003

2-26

Linking Mixed-Language Programs

Overruling the Run-Time Consistency Check

The run-time consistency check can be overruled by the option -set
float_lib_overrule on. If you overrule the consistency check, the operating

system allows a floating-point inconsistency between the user library and the program.
If you do not set float_lib_overrule, and there is an inconsistency between the
program file and user library, the operating system generates an error code and does
not run the program.

If the float_lib_overrule is specified more than once by either the -set or

-change option, all occurrences except the last one are ignored. The

float_lib_overrule attribute can be changed only for loadfiles. An error occurs if

an attempt is made to change the value of this attribute for linkfiles.

Linking Mixed-Language Programs

When linking m ixed-lan guag e programs that use IE EE flo ating- poi nt fo rma t, specify the

-set floattype IEEE_FLOAT option.

For example, suppose that you have a mixed-language program composed of the
following modules:

•

A C module that uses IEEE floating-point format

•

A COBOL module that does not use floating-point format but is marked by the
COBOL compiler as TANDEM_FLOAT

When you link the modules together, you can do either of the following:

•

Use the -set floattype IEEE_FLOAT option to set th e floatin g-po int type o f the
output object file to IEEE floating-point format.

•

Use the -change command to change the floating-point type of the COBOL object
file to NEUTRAL_FLOAT.

Example 2-11 links a mixed-language program that uses IEEE floating-point format.

The native C object file named COBJ uses IEEE floating-point format and the pTAL
object file uses Tandem floating-point format. (pTAL supports only Tandem floating­point format.) If this nld command did not include the option -set floattype
IEEE_FLOAT, nld would issue error messages because of the mismatch between
Tandem and IEEE floating-point formats. Because this nld command does include the
option -set floattype IEEE_FLOAT, nld issues a warning message about the
mismatch and builds the loadfile MYEXEC. CRTLMAIN (a linkfile) and the LIBCOBEY
file (an Obey command file) are standard items required when linking C programs.

Example 2-11. Linking a Mixed-Language Program With IEEE Floating-Point
Format

nld $system.system.crtlmain cobj ptalobj -obey &
$system.system.licbobey -set floattype ieee_float -o myexec

nld Utility

nld and noft Manual—520384-003

2-27

Searching for Archives and SRLs With Simple

Filenames

Searching for Archives and SRLs With Simple
Filenames

A simple name is a Guardian file identifier or an OSS pathname without any directory
components.

By default, nld searches a standard set of library locations for archive files and SRLs
specified with simple names in the option -l or -lib on page 3-7. You can stop nld from
searching the standard library locations with the option -nostdlib on page 3-9. nld
does not search the standard library locations for archive files and SRLs specified with
simple names on the nld command line.

Each version of nld searches a particular set of standard library locations:

•

The Guardian version of nld searc hes for S RLs and arch ive files in the sub volume
with the current version of the operating system image (the active
$SYSTEM.SYSnn subvolume).

•

The OSS version of nld searches for SRLs and archive files in the following
standard library locations, in the order shown:

1. The directory with the current ve rsion of the oper ating system im age ( the active

/G/system/sysnn directory).

2. The /lib directory.

3. The /usr/lib directory.

4. The /usr/local/lib directory.
In the OSS environment, the value of the COMP_ROOT environment variable is

added to the beginning of /lib, /usr/lib, and /user/local/lib. By default,
the value of COMP_ROOT is null.

The Guardian version of nld does not modify the simple name. The OSS version of
nld modifies the simple name as follows:

In dynamic linking, nld first looks for a file named libFilename.srl and then for a
file named libFilename.a. In static linking, nld looks only for a file named
libFilename.a. nld follows this process in each directory it is searching before
moving on to the next directory.

Dynamic and static linking are controlled with the -bdynamic and -bstatic flags.
See Dynamic and Static Linking on page 2-28 for details.

Note. This subsection does not apply to the PC. On the PC, you must specify the location for

nld to look for SRLs and archives; there are no stan dard librar y loc at ions.

Linking Specified Prefix Added to Simple Name Suffix Added to Simple Name

Dynamic lib .srl
Static lib .a

nld Utility

nld and noft Manual—520384-003

2-28

Dynamic and Static Linking

If the -verbose flag is specified, nld writes to its output listing the locations where it
found an SRL or archive file. (The Guardian version of nld has -verbose set by
default.) For more information, see -verbose on page 3-16.

In Example 2-12, the Guardian version of nld performs dynamic link ing (the default)
and searches for the C run-time library (ZCRTLSRL) and the CRE library (ZCRESRL)
SRLs in the subvolume with the current version of the operating system image.

In Example 2-13, the OSS version of nld performs dynamic linking (the default) and
searches for the C run-time library (ZCRTLSRL) and the CRE library (ZCRESRL)
SRLs in the subvolume with the current version of the operating system image. This
subvolume is in the Guardian file system although nld accesses the subvolume using
the OSS /G pathname syntax. Because the files are in the Guardian file system, nld
does not modify the simple name.

In Example 2-14, the OSS version of nld performs dynamic linking (the default) and
searches for the COBOL run-time library (ZCOBSRL) and the CRE library (ZCRESRL)
SRLs in the subvolume with the current version of the operating system image.

Dynamic and Static Linking

The flags -bdynamic on page 3-3 and -bstatic on page 3-4 specify dynamic and static
linking, respectively.

If the -bdynamic flag is specified, nld first searches for a shared run-time library
(SRL). If an SRL cannot be found, nld searches for an archive file. If neither file is
found, nld issues an error message. nld follows this process in each location (a
subvolume or directory) it is searching before moving on to the next location.

If the -bstatic flag is specified, nld searches for an archive file. nld does not
search for an SRL. If the archive file cannot be found, nld issues an error message.

Both the -bdynamic flag and the -bstatic flag can be specified in a single nld
invocation. Thus, it is possible to perform dynamic linking for some -l and -lib
options and static linking for others.

Example 2-12. Searching for ZCRTLSRL and ZCRESRL (Guardian)

NLD OBJECTA OBJECTB -l ZCRTLSRL -l ZCRESRL

Example 2-13. Searching for ZCRTLSRL and ZCRESRL (OSS)

nld objecta.o objectb.o -l ZCRTLSRL -l ZCRESRL

Example 2-14. Searching for ZCOBSRL and ZCRESRL (OSS)

nld a.out b.out -l ZCOBSRL -l ZCRESRL

nld Utility

nld and noft Manual—520384-003

2-29

Stripping Symbol Information

Stripping Symbol Information

Native object files contain symbol information to be used when linking or debugging.
The amount of symbol information produced by a compilation can be controlled by the
SYMBOLS compiler directive or pragma.

The nld utility can remove some or all symbol information as it creates an output file.

If you use -strip to remove the symbol information from an existing loadfile, the
result is the same as if you had used -s when you created the object file.

The -x option is similar to the Binder command STRIP SYMBOLS. You can partially
strip an existing object file by giving nld only one input filename and giving it the same
input filename for the o utput filename. If the symbol information is p ar tiall y stripp ed w ith

-x and you specify -r on page 3-11, you can use the output file again as nld input.

If the symbol information is completely stripped with the -s flag, then the file cannot be
used as nld input. It is not possible to use -s and -r together.

Outside of nld, you can remove symbol information from an existing loadfile with the
strip utility. See Section 7, strip Utility.

nld Compilation Rules

The nld utility enforces separate compilation rules for linking native programs in C,
C++, COBOL, and pTAL.

Subsections:

•

Case Sensitivity on page 2-29

•

Local and Shared Symbols on page 2-30

•

Declaration and Definition on pa ge 2-31

Case Sensitivity

C and C++ are case-sensitive; COBOL and pTAL are not. In C and C++, the symbol
names x and X refer to different symbols. In COBOL and pTAL, all symbol names are
converted to uppercase, so x and X refer to the same symbol.

Option Strips symbol information used for ... From ...

-s

on page 3-12 Linking and symbolic debugging Lo adfile

-strip

on page 3-16 Linking and symbolic debugging Existing loadfile

-x

on page 3-17 Symb olic debugging Loadfi le

nld Utility

nld and noft Manual—520384-003

2-30

Local and Shared Symbols

Local and Shared Symbols

A local symbol is known only within a single compilation unit. A shared symbol is
known by all compilation units that are linked together.

A local symbol is distinct from any other symbol of the same name that appears in
other compilation uni t s. Be cause a share d symbo l is know n by all com pil ation u nit s that
are linked together, all compilation units refer to the same symbol at run time.

The pTAL compiler has various rules for grouping data items into blocks. It is possible
to declare separate data items in pTAL, outside any explicit data blocks, and have
them remain individual data items across separate compilation units. (This behavior is
identical to that in C and C++.) The pTAL compiler can also group data items together
into a single data bl ock nam ed _GLOBAL. The pTAL compiler can also put the pre fix “$”
on the name of a data block. See the pTAL Reference Manual for details on declaring
and sharing data blocks in pTAL.

Table 2-6. Local and Shared Symbols by Language

Language Local Symbols: Names of ... Shared Symbols: Names of ...

C
C++

Static data items
Static functions

Data items declared outside functions
All other functions

COBOL Data records (level 01 data items) that

are not dec lared extern al
Subordi nat e data items (levels 02-nn)
Programs nested withi n ot her

programs

Exte rnal data items
External file connectors

pTAL Private data blocks whose NAME

declarations are unique
Subprocedures
Names of data bloc k members *

All other data block s

* For example, if a data block is named B and it contains an integer named I, then B is the only name that nld
considers for separate compilation rules. It is possible that B will be confused with a data item named B in C
compilation units.

nld Utility

nld and noft Manual—520384-003

2-31

Declaration and Definition

Declar ation and Definition

For data items shared across compilation units the difference between a declaration
and a definition is important.

Except for data that is exported from a user library, every data item must be defined at
least once when nld is building a loadfile. (If a data item is supposed to come from an
SRL, then it must not be defined within the program using the SRL.) If a data item is
never defined, you will get a run-time error when you execute your program. If you get
such an error, change your pTAL, C, or C++ source code so the data item is defined in
one of your compilation units. For example, you might need to provide a definition in
one of your C compilation units, or use the EXPORT_GLOBALS directive for your pTAL
compilation.

Data items defined in multiple COBOL or pTAL compilation units can be initialized
more than once, but all initial values for the same data item must be the same. Only
one C compilation unit is allowed to initialize a given data item.

nld does not perform type checking of symbols shared across compilation units.
When a data item is defined more than once, nld checks only that the size is the
same in all the definitions.

The body of a procedure is its definition and only one copy of that body can exist. It is
acceptable, however, for a body to be absent (the same is true for data, which—like
procedures—can be found in SRLs). If the body does not exist, the operating system
searches for the procedure at run time in the system library or a user library.

You can use the noft utility to examine symbol declarations and definitions in object
files. For more information on the noft utility, see Section 4, noft Utility.

Definition: The compiler allocates space for the data item, possibly giving it an

initial value.

Declaration: A compilation unit recognizes a data item, so the code can refer to it,

but this compilation unit has not allocated space for it.

Table 2-7. Declarations and Definitions by Lang uage

Language Declarations Definitions

C
C++

A data item is considered a
declaration if it is ext ernal and has no
initial valu e

Data items that are not external,
have initial values, or both

COBOL N o provision for declaration s All data items
pTAL A data item is considered a

declaration if the compiler directive
EXPORT_GLOBALS is set (this is the
default)

Data item s d ef ined when the
compiler directive EXPORT_GLOBALS
is not set

nld Utility

nld and noft Manual—520384-003

2-32

Declaration and Definition

nld and noft Manual—520384-003

3-1

3 nld Options

An option is a flag and its parameters, if any. You use the nld options to specify the
input object file, control the nld environment, and control the format of nld output.
This section describes the syntax and semantics of nld options and provides
examples of each option.

Table 3-1. nld Flag Summary (page 1 of 2)

Flag Description

-allow_duplicate_procs

on page 3-2

Directs nld not to report an error if more than one procedure has
the given name.

-allow_missing_libs

on

page 3-3

Prevents nld from stopping when it ca nnot find an archive or
SRL.

-allow_multiple_mains

on page 3-3

Specifies that mo re t han one procedure can hav e the MAIN
attribute.

-ansistreams

on

page 3-3

Specifies that C run-time library functions create files of type 180.

-bdynamic

on page 3-3 Directs nld to search for shared run-time libraries (SRLs) and

archive files when resolving -l and -lib opt ions.

-bstatic

on page 3-4 Directs nld to search for archive files when resolving -l and

-lib options.

-change

on page 3-4 Changes a ru n-t ime attribu te to a s pec ified value in an existing

loadfile.

-e

on page 3-5 Identifies the f unction at wh ic h th e program is to begin execu t ing

when th e program is loaded.

-elf_check

on page 3-5 Directs nld to check a loadfile for corruptions that might have

occurred.

-export

on page 3-5 Specifies that a symbol is exported by the user library or SRL

being created.

-fl or -obey

on page 3-6 Specifies the nam e of an nld command file containing nld

command tokens.

-import

on page 3-6 Imports a spec ified unres olv ed symbol fro m th e SRL.

-l or -lib

on page 3-7 Specifies an SRL or arch iv e f ile to resolve ex t ernal referenc es

from the linkfile being linked.

-L or -libvol

on page 3-8 Specifies a location to search for an SRL or archive file specified

by a simple f ilename in -l and -lib options.

-libname

on page 3-9 Associates a TNS/R native user library with an native loadfile.

-nostdfiles

on page 3-9 Specifies that C run-time library functions do not open the

standard input and standard output files automatically.

-nostdlib

on page 3-9 Prevents nld from searching the standard library locations for

SRLs and archive files.

nld Options

nld and noft Manual—520384-003

3-2

-allow_duplicate_procs

-allow_duplicate_procs

Causes nld to unconditionally accept multiple copies of procedures, rather than to
accept multiple copies of procedures only if the procedures are marked as duplicatable
by C++.

The only check made is that all copies of the procedure have the same procedure
attributes; it is a ccept able, fo r exam pl e, if they ha ve dif fer ent si zes. The fi rst cop y of the
duplicated procedure is the one that is kept. When building a loadfile, no space is
allocated for the unused copies.

-noverbose on

page 3-10

Prevents nld from writing warning and informa tio nal messages
to its output listing.

-NS_extent_size

on

page 3-10

Changes the extent size from the default (32 pages) to the
specified size.

-NS_max_extents

on

page 3-10

Changes the maximum number of extents from the default (900)
to the specified number.

-o

on page 3-11 Specifies the name of the output object file.

-obey Specifies the name of an nld command file containing nld
command tokens. See -fl or -obe y

on page 3-6.

-r

on page 3-11 Directs nld to create a relinkable object file.

-rename

on page 3-12 Changes the name of an externally visible procedure or data

item.

-s

on page 3-12 Removes s y m bol information used for lin ki ng and symbolic

debugg ing from the out put loadfile.

-set

on page 3-13 Sets a run-time attribute to a specified value when creating a

loadfile.

-stdin

on page 3-15 Reads the contents of the standar d input file.

-strip

on page 3-16 Removes symbol information used for lin ki ng and symbolic

debugg ing from an exis tin g loadfile.

-ul

on page 3-16 Cre at es a T N S/R native user library.

-verbose on page 3-16

Directs nld to write warning and informational messages to its
output list ing.

-x

on page 3-17 Removes s y m bol information used for sy m bolic debugging from

the output object file.

-y

on page 3-17 Identifies which object files define and use a symbol.

-allow_duplicate_procs

Table 3-1. nld Flag Summary (page 2 of 2)

Flag Description

nld Options

nld and noft Manual—520384-003

3-3

-allow_missing_libs

-allow_missing_libs

Prevents nld from stopping when it cannot find an archive or SRL specified by -l or -lib
on page 3-7. Instead of stopping, nld issues a warning and continues to process the
input file.

-allow_multiple_mains

Prevents nld from issuing an error message if more than one procedure has the MAIN
attribute.

All “main” procedures are included in the output file, but only the first procedure having
the MAIN attribute is listed as the main entry point in the file header.

-ansistreams

Causes C run-time l ibr ary fu nctions to create fi les of type 180 (C b inary) in stead o f type
101(edit).

The type of files created can also be set with the ANSISTREAMS C and C++ compiler
pragma. See the C/C++ Programmer’s Guide for details.

-bdynamic

Causes nld to search for shared run-time libraries (SRLs) and archive files when
resolving -l or -lib

on page 3-7. This is the default.

nld first searches for an SRL. If an SRL cannot be found, nld searches for an archive
file. nld follows this process in each location (a subvolume or directory) it is searching
before moving on to the next location.

-bdynamic can be disabled by -bstatic on page 3-4. Multiple -bdynamic and

-bstatic flags can be specified in a single nld invocation, each one taking effect at

the point at which it appears on the command line. Thus, it is possible to search for
SRLs and archive files for some -l and -lib options and just archive files for others.

-allow_missing_libs

-allow_multiple_mains

-ansistreams

-bdynamic

nld Options

nld and noft Manual—520384-003

3-4

-bstatic

-bstatic

Causes nld to search for archive files when resolving -l or -lib on page 3-7.

nld searches for an archive file. nld does not search for an SRL. nld issues

an error if an archive file cannot be found.

-bstatic can be disabled by -bdynamic on page 3-3. Multiple -bdynamic and

-bstatic flags can be specified in a single nld invocation, each one taking effect at

the point at which it appears on the command line. Thus, it is possible to search for
SRLs and archive files for some -l and -lib options and just archive files for others.

-change

Changes a run-time attribute to a specified value in an existing loadfile. (To set an
attribute when creating a loadfile, use -set on page 3-13.)

attribute-name

is a run-time attribute.

attribute-value

is the value to which the specified run-time attribute is to be set. Each run-time
attribute has a corresponding range of accepted values (see Table 3-2 on
page 3-13).

filename

is a loadfile.

If you also specify -verbose on page 3-16, then a summary and the elapsed time are
provided at termination.

You cannot specify other options or object filenames with -change. The resulting
loadfile has the same nld timestamp as before.

-bstatic

-change attribute-name attribute-value filename

nld Options

nld and noft Manual—520384-003

3-5

-e

-e

Identifies the function at which the program is to begin executing when the program is
loaded. Without -e, the program begins executing at the function that has the MAIN
attribute.

function-name

is the name of the function at which the program is to begin executing when the
program is loaded.

-elf_check

Causes nld to check a loadfile for corruptions that were caused by older versions of
nld and Guardian. These corruptions might have occurred in the following situations:

•

Unresolved reference s in the dat a portio n of the fi le that were not al igned on 4-byte
boundaries were later resolved.

•

The PC ver sion of nld changed the file header during an SRL fixup operation.

filename

the name of the loadfile to be checked for corruptions.

-export

Specifies that a symbol is exported by the user library or SRL being created.

symbol_name

is the name of the symbol to be exported by the SRL being created.

Note. Use only w hen linking a program (not a libra ry) that wil l run without t he s t andard run ­time support facilities.

-e function-name

-elf_check filename

Note. -elf_check is a read-only operation.

-export symbol_name

nld Options

nld and noft Manual—520384-003

3-6

-fl or -obey

-fl or -obey

Specifies the name of an nld command file containing nld command tokens.

filename

is an edit file (for the Guardian version of nld) or a C text file (for the OSS version
of nld).

Tokens can be separated by spaces, tabs, or ends of lines. Within the command file,
two hyphens indicate a comment that extends to the end of the current line. Command
files can be nested and there is no limit to the dep th of nesting. R ecur sive nesting does
not cause an error; nld does not read the same command file more than once.

-import

For HP internal use in constructing SRLs. Imports an unresolved symbol from the SRL.

symbol_name

is the name of the unresolved symbol to be imported from the SRL.

filename

is the external name of the SRL that contains symbol_name. The filename
cannot be a map DEFINE name.

srlname

is the internal name of the SRL that contains symbol_name.

Searches for symbol_name in an S RL are gover ned by -L or -libvol on page 3-8, using
the rules for -l or -lib on page 3-7.

Do not use -import with -r on page 3-11.

{ -fl | -obey } filename

-import symbol_name { filename | =srlname }

nld Options

nld and noft Manual—520384-003

3-7

-l or -lib

-l or -lib

Specifies a shared run-time library (SRL) or archive file to use to resolve external
references from the loadfile being linked.

filename

specifies an SRL or archive file, either by name or (in the Guardian environment)
by map DEFINE.

-l must be lowercase. The space after the flag is optional.
A simple name is a Guardian file identifier or a OSS pathname without any directory

components.
If filename is not a simple name, nld searches the specified location.
If filename is a simple name, the OSS workstation versions of nld adds the string

lib to the beginning of the name. These versions also add either .a or .srl to the
end of the name, depending on whether dynamic or static linking is being performed.
Files with the suffix .a are archive files, and files wi th the suf f ix .srl are S RLs. S imple
filenames in the Guardian file system, /G, are not modified. See Dynamic and Static

Linking on page 2-28 for more details.

nld searches for files specified with simple names in the options -l or -lib in
locations specified in those opt ions, in the order specified to nld, before searching any
of the standard library locations. Each version of nld searches a particular set of
standard library locations. See Dynamic and Static Linking on page 2-28 for details.

If you specify the -nostdlib on page 3-9, nld does not search the standard library
locations.

-l[ib][ ]filename

nld Options

nld and noft Manual—520384-003

3-8

-L or -libvol

-L or -lib v o l

Specifies a location to search for a shared run-time library (SRL) or archive file
specified by a simple filename in -l or -lib on page 3-7. A simple filename is a Guardian
file identifier or an OSS pathname without any directory components.

location

is the location to search. For the Guardian version of nld, location is a
Guardian subvolume. For the OSS version of nld, location is an OSS directory
pathname.

-L must be uppercase. The space after the flag is optional.
nld searches for files specified with simple names in -l and -lib options in locations

specified in each -L and -libvol option, in the order specified to nld, before
searching any of the standard library locations. Each version of nld searches a
particular set of standard library locations. See Searching for Archives and SRLs With

Simple Filenames on page 2-27 for details.

If you specify -nostdlib on page 3-9, nld does not search the standard library
locations.

nld does not verify the names of locations specified in -L options.
If you specify -verbose on page 3-16, nld writes to its output listing the locations

where it found an SRL or archive file. The Guardian version of nld has -verbose set
by default.

{ -L | -libvol }[ ]location

nld Options

nld and noft Manual—520384-003

3-9

-libname

-libname

Associates a TNS/R native user library with a native loadfile.

filename

is the Guardian name of the TNS/R native user library to be associated with the
native loadfile. It must include volume and subvolume, and its length must not
exceed 48 characters.

User libraries must have Guardian names. In OSS, filename must be in a form that
points to a Guardian file. In the following examples, the two -libname options point to
the same user library.

You can associate a TNS/R native user library with a loadfile but not with a linkfile. -set
on page 3-13 and -change on page 3-4 can also associate a TNS/R native user library
with a native loadfile.

-nostdfiles

Specifies that C run-time library functions do not open the standard input and standard
output files automatically.

-nostdlib

Prevents nld from searching the sta ndar d librar y l ocation s for sha red r un- time l ibra ries
(SRLs) and archive files.

See Searching for Archives and SRLs With Simple Filenames on page 2-27 for a list of
the standard library locations.

-libname filename

Environment Com m and Location Example

Guard ian Either in a file or on t he

command line

-libname $NATIV1.CRGLIB.NLIB

OSS In a file

-libname /G/NATIV1/CRGLIB/NLIB

On the command line

-libname \$NATIV1.CRGLIB.NLIB

-nostdfiles

-nostdlib

nld Options

nld and noft Manual—520384-003

3-10

-noverbose

-noverbose

Prevents nld from writing warning and informational messages to its output listing.

-verbose on page 3-16 causes nld to write warning and informational messages to its

output listing. The default for the OSS and PC versions of nld is -noverbose. The
default for the Guardian version of nld is -verbose.

-NS_extent_size

Changes the extent size from the default (32 pages) to the specified size.

extent-size

is an even number in the range 2 to 65534, inclusive.
A page has 2048 bytes.
nld uses extent-size for both primary and secondary extents.

-NS_max_extents

Changes the maximum number of extents from the default (900) to the specified
number.

max-extents

is a number in the range 16 to 900, inclusive.

-noverbose

Note. Guardian environment only.

-NS_extent_size extent-size

Note. Guardian environment only.

-NS_max_extents max-extents

Note. The Guardian P roc edure Calls R efere nc e M anual recommends that max-extents

not exceed 500.

nld Options

nld and noft Manual—520384-003

3-11

-o

-o

Specifies the name of the output object file.

filename

is the name of the output file, either by name or (in the Guardian environment) by

map DEFINE. This filename can be the same as the input filename. If linking is

successful, nld deletes the input file and then writes the output file. An error

occurs if you do not have permission to delete the input file.

If filename exists and is not in use, nld appends the listing to the file.

If filename exists and is in use, nld makes up to 10 attempts to change the name

of filename to ZZNDnnnn. If these 10 attempts fail, nld makes up to 10 attempts

to create a new file named ZZNDnnnn. If these 10 attempts also fail, no file

containing the new information is created and nld reports an error.
If you do not specify a -o option, the default output filename is a.out in the OSS

environment and AOUT in the Guardian environment.
The output file first created by nld has a temporary filename that is later renamed to

either the default filename or the filename specified with the -o option. An abnormal
termination of nld can produce a file with a temporary filename in the OSS
environment. The OSS filename is of the form ZZNLDnnn.

-r

Causes nld to create a linkfile instead of a loadfile. nld creates a loadfile by default.

See Native Object Files

on page 1-2 for information on the characteristics of linkfiles

and loadfiles.

-o filename

-r

nld Options

nld and noft Manual—520384-003

3-12

-rename

-rename

Changes the name of an externally visible procedure or data item.

old-name

is the name of the procedure or data item to rename.

new-name

is the new name to give the procedure or data item.
Existing references to the current name become unresolved references. Thus, another

procedure or data item named old-name can be linked and existing code will use this
version instead of the original (now renamed) version. For example, procedure A calls
procedure B. The operation -rename B C renames procedure B to procedure C.
Procedure A now has an unresolved reference. A new version of procedure B can be
linked in. The new version of procedure B can call the original procedure by calling
procedure C.

Use this option to replace procedures, such as PROCESS_LAUNCH_, with your own
version of PROCESS_LAUNCH_.

-s

Removes symbol information used for linking and symbolic debugging from the
loadfile.

A file stripped of all symbol information cannot be symbolically debugged with the
Inspect symbolic debugger or linked again by nld.

You can use -s only when creating a loadfile. If you specify both -r on page 3-11 and

-s, -s is ignored. To strip all symbol information from an existing loadfile, use -strip on
page 3-16. You can strip the symbol information used for symbolic debugging with -x
on page 3-17.

-rename old-name new-name

-s

nld Options

nld and noft Manual—520384-003

3-13

-set

-set

The -set option sets a run-time attribute to a specified value when creating a loadfile.
(To change a run-time attribute in an existing loadfile, see -change on page 3-4.)

attribute-name

is a run-time attribute (see Table 3-2).

attribute-value

is the value to which the specified run-time attribute is to be set (see Table 3-2 for

acceptable values and Table 3-3 on page 3-15 for default values).

-set attribute-name attribute-value

Table 3-2. Descriptions of Run-Time Attributes (page 1 of 2)

attribute-name attribute-value Description

FLOAT_LIB_OVERRULE ON

OFF

If it is ON, fl o at-type consis tency
checks be t w een the program being
run an d t he user librar y (speci f ied by
the LIB run-time para m et er) are
suppressed.

FLOATTYPE TANDEM_FLOAT

IEEE_FLOAT
NEUTRAL_FLOAT

Sets the object file’s floating-point
type to eith er Tandem floating-point,
IEEE floa ti ng-point, or ne ut ral.
Neutral means that the object file
can be linked with an object file of
any floating-point type, and that it
can be executed whether or not the
processor supports IEEE floating­point. For descriptions of Tandem
and IEEE f loating-point fo rm ats, see
the Gua rdian Progra m m er’s Guide.

HEAP_MAX Number in th e range

from 0 through
2,147,483,647
(0x7FFFFFFF).

1

Sets the maximum size of the heap.

HIGHPIN ON

OFF

Specifies whether an object file runs
at a high proc ess identification
number (PIN) if the process creation
request a llow s it and a high PIN is
available.

1. The fact that nld allows you to use these numbers to buil d a program does not mean that the program will
run. System memory configuration sizes and setting might prevent the program from running if ver y large values
have been set.

nld Options

nld and noft Manual—520384-003

3-14

-set

HIGHREQUESTER
HIGHREQUESTERS
HIGHREQUESTOR
HIGHREQUESTORS

ON
OFF

Specifies whether an object file can
support high process identi fication
number (PIN) request ers.

INSPECT ON

OFF

Specifies whether the Inspec t
program is c hosen for deb ugging
when you execute the target file.

LIBNAME

filename

Associates a TNS/R native user
library with a native program file.

MAINSTACK_MAX N um ber in the range

from 0 through
2,147,483,647
(0x7FFFFFFF).*

Sets the maximum size of the main
stack.

RUNNAMED ON

OFF

Specifies whether an object file runs
as a named process, even if no RUN
command named param eter is
specified.

PFS
PFS_SIZE

Number in th e range
from 0 through
2,147,483,647
(0x7FFFFFFF).*

Specifies the byte size of the
process file segment. This value is
insignificant as of RVU G06.

PROCESS_SUBTYPE
SUBTYPE

Number in th e range
from 0 through
2,147,483,647
(0x7FFFFFFF).*

Sets the process subtype for the
output ob jec t fi le.

SAVEABEND ON

OFF

Specifies whether or not to create a
save file if the process terminates
abnormally during execution.

SPACE_GUARANTEE Number in the rang e

from 0 through
2,147,483,647
(0x7FFFFFFF).*

Sets the space s iz e.

SYSTYPE OSS

GUARDIAN

Speci fi e s whether the object fi le is to
run as an OSS or Guardian process.
Setting this at tr ibu te t o OSS also sets
the -ansistreams flag when the

-set option is used but not when
the -change option is used.

Table 3-2. Descriptions of Run-Time Attributes (page 2 of 2)

attribute-name attribute-value Description

1. The fact that nld allows you to use these numbers to buil d a program does not mean that the program will
run. System memory configuration sizes and setting might prevent the program from running if ver y large values
have been set.

nld Options

nld and noft Manual—520384-003

3-15

-stdin

-stdin

Reads the contents of the standard input file at the specified place the flag is specified
on the command line.

Table 3-3. Default Run-Time Attribute Values

attribute-name Default attribute-value

FLOATTYPE

(for ELF files only)

If FLOATTYPE is not specified, nld derives the fl oat ing-point type
of the output object file from the types of the input files. For
details, see the C/C++ Programmer’s Guide.

HEAP_MAX 0 (The operating system provides the default heap size.)
HIGHPIN ON
HIGHREQUESTER

HIGHREQUESTERS
HIGHREQUESTOR
HIGHREQUESTORS

ON

INSPECT ON
LIBNAME None.
MAINSTACK_MAX 0 (The operating system provides the default stack size.)
RUNNAMED OFF
PFS

PFS_SIZE

0

PROCESS_SUBTYPE
SUBTYPE

0

SAVEABEND OFF
SPACE_GUARANTEE 0
SYSTYPE OSS when using the OSS version of nld. GUARDIAN when using

the Guardian or PC version of nld.

-stdin

nld Options

nld and noft Manual—520384-003

3-16

-strip

-strip

Removes symbol information used for l inking and symbol ic debugg ing from an exist ing
loadfile.

filename

is the name or (in the Guardian environment) the map DEFINE of the object file to

strip.
A file stripped of all symbol information cannot be symbolically debugged with Inspect

or linked again by nld.
You can use -strip only on an existing loadfile. To strip all symbol information when

creating a loadfile, use -s on p age 3-12. You can strip only the symbol infor matio n used
for symbolic debugging with the -x on page 3-17.

You cannot specify any other options or object filenames with the -strip option. The
resulting file has the same nld timestamp as before.

-ul

Creates a TNS/R native user library.

Use -ul when linking fil es toget her to cr eate a T NS/R na tive user library. Use -libname
on page 3-9 to associate a TNS/R native user library with a TNS/R native user
program. See Linking User Libraries on page 2-13 for more details.

-verbose

Causes nld to write warning and informational messages to its output listing.

-noverbose on page 3-10 prevents nld from writing warning and informational

messages to its output listing. The default for the OSS and PC versions of nld is

-noverbose. The default for the Guardian version of nld is -noverbose.

-strip filename

-ul

-verbose

nld Options

nld and noft Manual—520384-003

3-17

-x

-x

Removes symbol information used for symbolic debugging from the output file.

This action often decreases the size of an object file. The file cannot be symbolically
debugged with Inspect, but enough information remains so the object file can be used
as nld input again. This flag is often used with -r on page 3-11.

If you specify only one input filename and use both -x and -r, and you specify the
same filename again for the output file with -o on page 3-11, you can partially strip a
file in place. The resulting file has a new nld timestamp. The resulting object file is not
necessarily smaller than the original file.

-y

Identifies the object files that define and use a specified symbol.

symbol

is the symbol to report on.
If you use -verbose on page 3-16, nld writes to its output listing information to identify

which object files define and use the specified symbol. This information can be useful if
a previous nld session produced error or warning messages about a symbol being
either undefined or defined more than once.

-x

-y symbol

nld Options

nld and noft Manual—520384-003

3-18

-y

nld and noft Manual—520384-003

4-1

4 noft Utility

The noft utility, the native object file tool, displays all portions of native object files.
Subsections:

•

Running the noft Utility in the Guardian Environment on page 4-1

•

Running the noft Utility in the OSS Environment on page 4-3

•

Listing Object Files on page 4-4

•

Dumping Object Files on page 4-5

•

Controlling the noft Environment on page 4-5

•

Debugging With noft on page 4-7

Running the noft Utility in the Guardian
Environment

You can use the noft utility as an interactive or batch process, but noft is most often
used as an interactive process. To run the noft utility in the Guardian environment,
use the TACL command RUN. The most common forms of RUN used for noft follow.
For complete information on RUN, see the TACL Reference Manual.

[RUN] NOFT

is the TACL command to start the noft process.

command-file

is an edit file containing one or more noft options. If the file contains more than

one option, options must be separated by semicolons (;).

If both a command-file and options are given, noft ignores the command-file.

To run noft interactively:

[RUN] NOFT

To quit running noft interactively:

{ EXIT | E | QUIT | Q }

To run noft with a command file:

[RUN] NOFT [ / IN command-file [, OUT output-filename ] / ]

To run noft from the command line:

[RUN] NOFT option [; option ]...

noft Utility

nld and noft Manual—520384-003

4-2

Running the noft Utility in the Guardian Environment

output-filename

specifies a Guardian filename to which noft writes its output. If you specify a disk

filename and the file does not exist, noft creates an edit file. If the specified disk

file exists, noft appends to the file. If you omit the OUT option, noft writes its

output to your current default output file.

option

is one or more noft flags with their parameters, if any.

When you run noft from the command line:

•

Include the option FILE or F on page 5-15.

•

Do not include the following options, which work only in an interactive session:

°

! (Exclamation Point) on page 5-4

°

FC on page 5-14

•

Do not include the following, which are useful only in an interactive session:

°

The option HISTORY or H on page 5-20

°

The HISTORYBUFFER or HISTORYWINDOW parameter of the option SET
on page 5-42

(Options given in the command line are not stored in the history buffer.)

This section summarizes the noft flags. For further information, see Section 5, noft

Options.

noft Utility

nld and noft Manual—520384-003

4-3

Running the noft Utility in the OSS Environment

Running the noft Utility in the OSS
Environment

You can use the noft utility as an interactive or batch process, but noft is most often
used as an interactive pr ocess. To run the noft utility in the OSS environment, use the
following syntax:

option

is a noft flag and its parameters, if any. If you do not specify option, noft runs

as an interactive process.

When you run noft from the command line:

•

Include the option FILE or F on page 5-15.

•

Prefix each option with a hyphen (-); for example, -file.

•

If an option includes an asterisk (*) or question mark (?) as a parameter, do
either of the following:

°

Enclose the option and its parameters in quotation marks; for example:

noft -file sample "-listproc *"

°

Enclose the entire sequence of options in quotation marks; for example

noft "-file sample -listproc *"

•

Do not include the following options, which work only in an interactive session:

°

! (Exclamation Point) on page 5-4

°

FC on page 5-14

•

Do not include the following, which are useful only in an interactive session:

°

The option HISTORY or H on page 5-20

°

The HISTORYBUFFER or HISTORYWINDOW parameter of the option SET
on page 5-42

(Options given in the command line are not stored in the history buffer.)

object-filename

specifies the target object file.

noft [ option ] ... object-filename [ i-o-redirection ]

Example 4-1. noft Command Line

noft -file sample.o -set scopesource sample.c "-listproc *"

noft Utility

nld and noft Manual—520384-003

4-4

Listing Object Files

Listing Object Files

Example 4-2. Interactive noft Session Equivalent to Example 4-1 on page 4-3

noft
noft> file sample.o

noft> set scopesource sample.c
noft> listproc *
noft> exit

Table 4-1. noft Listing Opti on s

Option Lists ...

LAYOUT

on page 5-21 Parts of an object file in file-offset order

LISTATTRIBUTE or LA

on

page 5-22

Process-s pecific info rm at ion associat ed with an obje c t
file

LISTCOM PILERS or LC

on

page 5-23

Version information about the native compiler
components and nld utili ty used to create an object file

LISTOPTIMIZE or LO

on

page 5-26

Procedures in an objec t file based on opti m iz ation level

LISTPROC or LP

on page 5-27 Procedures and subproc edures in an object file

LISTSOURCE or LS

on

page 5-29

Source files in an object file

LISTSRLEXPORTS o r LLE

on

page 5-30

Informat ion about the sy m bols exported by a shared
run- t ime library (SRL )

LISTSRLF I XUPS or LLF

on

page 5-30

Names of SRLs to which the unresolved symbols in an
object file have been “fi xe d up”

LISTSRLI N F O or LLI

on

page 5-31

Names of SRLs linked into an object file

LISTUNREFERENCED or LUR

on page 5-32

Undefined and unreferenced symbols in an object file

LISTUN R ESOLVED o r LU

on

page 5-35

Unresolved symbols in an object file

XREFPROC or XP

on page 5-49 C ross referenc e lis t ing of proced ures in an objec t file

noft Utility

nld and noft Manual—520384-003

4-5

Dumping Object Files

Dumping Object Files

The noft dumping options display unformatted views into an object file.

Controlling the noft Environment

Table 4-2. noft Dumpin g Optio ns

Option Displays ...

DUMPADDRESS or DA

on

page 5-6

Code and data from a virtual address ins ide an object file ’s
memory space

DUMPOFFSET or DO

on

page 5-8

Code and data from a physical offset within the object file

DUMPPROC or DP

on

page 5-10

Conten ts of a procedure or part of a procedure

Table 4-3. noft Contro l Opti o ns (page 1 of 2)

Option Description

Break Key

on page 5-3 Interrupts the processing of the current option.

! (Exclamation Point)

on

page 5-4

Executes a previ ously executed command line.

CD

on page 5-5 Changes the current working directory used to se arc h for

relative filenames. (Use only in OSS environment.)

COMMENT

on page 5-5 Allow s co m m ents in noft command files.

ENV

on page 5-13 Displays the current set tin gs of environme nt parameters.

EXIT or E

on page 5-13 Stops the noft process.

FC

on page 5-14 Edits or repeats a previously executed command line.

FILE or F

on page 5-15 Specifies the name of the target obj ec t file .

HELP or ?

on page 5-17 Display s descriptions and syntax for opt ions.

HISTORY or H

on

page 5-20

Displays previously entered comm and lines.

LOG

on page 5-38 Writes a copy of the current noft se s s ion’s input and ou tp ut

to a file.

OBEY

on page 5-39 Di rec ts noft to read from a specified command file.

OUT

on page 5-39 Writes the input and outpu t lis tin gs t o a s pecified file.

QUIT or Q

on page 5-40 St ops the noft process.

RESET

on page 5-41 Res ets one or more noft target object file parameters

previous ly s pecified with a SET option to their default values.

noft Utility

nld and noft Manual—520384-003

4-6

Controlling the noft Environment

SET on page 5 -42 Sets one or more of th e fo llowing:

•

Case sensitivity of noft

•

Object file format

•

Number of command lines in memory available to the FC
or HISTORY option

•

Number of command lines displayed with the HISTORY
option

•

Name of log file

•

Name of file to which noft writes input and output listings

•

Scope of noft options to a single procedure or
subprocedure

•

Scope of noft options to a single source file

•

Sorting order of the output

SYSTEM or VOLUME

on

page 5-48

Specifies the default node, volume, and subvolume names
used to re s olv e partially-qu alif ied Guardia n f ilenames. (U se
only in the Guardian environment.)

Table 4-3. noft Contro l Opti o ns (page 2 of 2)

Option Description

noft Utility

nld and noft Manual—520384-003

4-7

Debugging With noft

Debugging With noft

The dumping options (listed in Table 4-2 on page 4-5) can be useful when debugging
optimized native object code, especially when you must debug code at the RISC
instruction-level.

Example 4-3 is followed by DUMPPROC listings of its compute() function compiled at

optimization levels 0, 1, and 2. After the listings is a comparison of optimization levels.

Note. You must use Visual Inspect, rather t han Inspect , to debug PIC executable files.

Example4-3. C Program

long compute(long a[]);
int main (void)

{
long z[10];
long x;
x=compute(z);
return 0;
}

long compute(long a[])
{
long b;
int c,i;
b=0;
for (i=0; i<20; i++)
b += a[i];
return b;
}

noft Utility

nld and noft Manual—520384-003

4-8

Debugging With noft

Example 4-4 shows the noft output for the compute() function in Example 4-3 on

page 4-7 compil ed at optimize 0. The na tive compilers perform no op timizations at
optimize 0.

Example 4-4. Optimize 0 Listing

noft> dumpproc compute
******** Innerlist Dump Of Procedure: compute ********

Procedure Src Line Address Long Word Instructions

------------------------------------------------------------------­ 14 long compute(long a[])
[compute 14000] 0x70000470 0x27bdfff8 addiu sp,sp,0xfffffff8
15 {

16 long b;
17 int c,i;
18 b=0;

[compute 18000] 0x70000474 0xafa00004 sw zero,0x4(sp)
19 for (i=0; i<20; i++)
[compute 19000] 0x70000478 0xafa00000 sw zero,0(sp)
20 b += a[i];
[compute 20000] 0x7000047c 0x8fae0004 lw t6,0x4(sp)

[compute 20000] 0x70000480 0x8faf0000 lw t7,0(sp)
[compute 20000] 0x70000484 0000000000 nop
[compute 20000] 0x70000488 0x000fc080 sll t8,t7,2
[compute 20000] 0x7000048c 0x0098c821 addu t9,a0,t8
[compute 20000] 0x70000490 0x8f280000 lw t0,0(t9)
[compute 20000] 0x70000494 0000000000 nop
[compute 20000] 0x70000498 0x01c84821 addu t1,t6,t0
[compute 20000] 0x7000049c 0xafa90004 sw t1,0x4(sp)
[compute 20000] 0x700004a0 0x25ea0001 addiu t2,t7,0x1
[compute 20000] 0x700004a4 0xafaa0000 sw t2,0(sp)
[compute 20000] 0x700004a8 0x29410014 slti at,t2,0x14
[compute 20000] 0x700004ac 0x1420fff3 bne at,zero,0x7000047c
[compute 20000] 0x700004b0 0000000000 nop

21 return b;
[compute 21000] 0x700004b4 0x8fa20004 lw v0,0x4(sp)

[compute 21000] 0x700004b8 0x10000001 b 0x700004c0
[compute 21000] 0x700004bc 0000000000 nop

22 }
[compute 22000] 0x700004c0 0x03e00008 jr ra

[compute 22000] 0x700004c4 0x27bd0008 addiu sp,sp,0x8

noft Utility

nld and noft Manual—520384-003

4-9

Debugging With noft

Example 4-5 shows the noft output for the compute() function in Example 4-3 on

page 4-7 compiled at optimize 1. T he native compilers perform many optimizations
at optimize 1.

Example 4-5. Optimize 1 Listing

noft> dumpproc compute
******** Innerlist Dump Of Procedure: compute ********

Procedure Src Line Address Long Word Instructions

------------------------------------------------------------------­ 14 long compute(long a[])
[compute 14000] 0x70000460 0x27bdfff8 addiu sp,sp,0xfffffff8
15 {

16 long b;
17 int c,i;
18 b=0;

[compute 18000] 0x70000464 0xafa00004 sw zero,0x4(sp)
19 for (i=0; i<20; i++)
[compute 19000] 0x70000468 0xafa00000 sw zero,0(sp)
20 b += a[i];
[compute 20000] 0x7000046c 0x8faf0000 lw t7,0(sp)

[compute 20000] 0x70000470 0x8fae0004 lw t6,0x4(sp)
[compute 20000] 0x70000474 0x000fc080 sll t8,t7,2
[compute 20000] 0x70000478 0x0098c821 addu t9,a0,t8
[compute 20000] 0x7000047c 0x8f280000 lw t0,0(t9)
[compute 20000] 0x70000480 0x25ea0001 addiu t2,t7,0x1
[compute 20000] 0x70000484 0x29410014 slti at,t2,0x14
[compute 20000] 0x70000488 0x01c84821 addu t1,t6,t0
[compute 20000] 0x7000048c 0xafa90004 sw t1,0x4(sp)
[compute 20000] 0x70000490 0x1420fff6 bne at,zero,0x7000046c
[compute 20000] 0x70000494 0xafaa0000 sw t2,0(sp)

21 return b;
[compute 21000] 0x70000498 0x8fa20004 lw v0,0x4(sp)

[compute 21000] 0x7000049c 0000000000 nop
22 }
[compute 22000] 0x700004a0 0x03e00008 jr ra

[compute 22000] 0x700004a4 0x27bd0008 addiu sp,sp,0x8

noft Utility

nld and noft Manual—520384-003

4-10

Debugging With noft

Example 4-6 shows the noft output for the compute() function in Example 4-3 on

page 4-7 compiled at optimize 2. T he native compilers perform all possible
optimizations at optimize 2. The “+” and “-” characters in the leftmost column
indicate code that has been moved forward or backward in the execution stream.

The following table shows the number of instructions required (the length of the
instruction stream) to run the compute() function in Example 4-3 on page 4-7 at each
optimization level:

At optimization level 0, the native compiler performs no optimizations. Notice that the
code contains nop (no operation) instructions and uses few registers.

Example 4-6. Optimize 2 Listing

noft> dumpproc compute
******** Innerlist Dump Of Procedure: compute ********

Procedure Src Line Address Long Word Instructions

------------------------------------------------------------------­ 19 for (i=0; i<20; i++)
[compute 19000] 0x70000450 0x00802825 move a1,a0

-[compute 18000] 0x70000454 0x00001825 move v1,zero
[compute 19000] 0x70000458 0x24040014 li a0,0x14
[compute 19000] 0x7000045c 0x00001025 move v0,zero

20 b += a[i];
[compute 20000] 0x70000460 0x8cae0000 lw t6,0(a1)

[compute 20000] 0x70000464 0x8caf0004 lw t7,0x4(a1)
[compute 20000] 0x70000468 0x8cb80008 lw t8,0x8(a1)
[compute 20000] 0x7000046c 0x006e1821 addu v1,v1,t6
[compute 20000] 0x70000470 0x8cb9000c lw t9,0xc(a1)
[compute 20000] 0x70000474 0x006f1821 addu v1,v1,t7
[compute 20000] 0x70000478 0x24420004 addiu v0,v0,0x4
[compute 20000] 0x7000047c 0x00781821 addu v1,v1,t8
[compute 20000] 0x70000480 0x24a50010 addiu a1,a1,0x10
[compute 20000] 0x70000484 0x1444fff6 bne v0,a0,0x70000460

[compute 20000] 0x70000488 0x00791821 addu v1,v1,t9
21 return b;
[compute 21000] 0x7000048c 0x03e00008 jr ra

[compute 21000] 0x70000490 0x00601025 move v0,v1

Optimization Level Number of Instructions

0269
1207
257

noft Utility

nld and noft Manual—520384-003

4-11

Debugging With noft

At optimization level 1, the native compiler:

•

Optimizes across statement boundaries to remove nop instructions.

•

Uses registers instead of memory.

•

Optimizes by finding common subexpressions.

•

At optimization level 2, the native compiler:

•

Replaced the variable i with a derived pointer expression or an induction variable.

•

Eliminates the parameter load and store operations at the procedure entrance by

placing the code inline. This can result in a larger object file.

•

Optimizes across compound statement boundaries. (A loop is an example of a

compound statemen t.)

•

Uses registers instead of using memory extensively.

•

Changes the loop to load four values at a time instead of one value at a time.
The difference between optimize 1 and optimize 2 is typically much less than it

is in Example 4-3 on page 4-7. This example was chosen to show how the compiler
optimization can result in quite different code at the source statement level. The
program at optimize 2 steps though the loop five times instead of 20 times. The
value of b is also quite different in each loop.

noft Utility

nld and noft Manual—520384-003

4-12

Debugging With noft

nld and noft Manual—520384-003

5-1

5 noft Options

An option is a flag and its parameters, if any. You use the noft options to specify the
input object file, control the noft environment, and control the format of noft output.
This section describes the syntax and semantics of noft options and provides
examples of each option.

Table 5-1 on page 5-1 lists the noft flags in alphabetical order. For tables that list

noft flags by function, see:

•

Table 4-1, noft Listing Options, on page 4-4

•

Table 4-2, noft Dumping Options, on page 4-5

•

Table 4-3, noft Control Options, on page 4-5

Table 5-1. noft Flag Summa r y (page 1 of 3)

Flag De scription

Break Key

on page 5-3 Terminates the output of the current option and, if noft

is running from the command line, te rm inates the noft
progr am itsel f .

! (Exclamation Point)

on page 5-4 Executes a previ ously executed co m m and line. (Use

only in an interactive session.)

CD

on page 5-5 Changes the current w orking directory used to se arc h

for relative filenames. (Use only in OSS environment.)

COMMENT

on page 5-5 Allows co m m ents in noft command files.

DUMPADDRESS or DA

on

page 5-6

Displays code and data from a virtual address inside an
object file’s memory space.

DUMPOFFSET or DO

on

page 5-8

Displays code and data from a physical offset within the
object file.

DUMPPROC or DP

on page 5-10 Displays t he contents of a procedure or part of a

procedure.

ENV

on page 5-13 Displays t he current set tin gs of environme nt

parameters.

EXIT or E

on page 5-13 Stops the noft process.

FC

on page 5-14 Edits or repea ts a previously executed com m and line.

(Use only in an interactive session.)

FILE or F

on page 5-15 Specifies the name of the target obj ec t file .

HELP or ?

on page 5-17 Displays descriptions and syntax for opt ions.

HISTORY or H

on page 5-20 Displays previously entered comm and lines. (Us e only

in an interactive session.)

LAYOUT

on page 5-21 Lists the parts o f an object file in order by file offset.

LISTATTRIBUTE or LA

on

page 5-22

Lists process-specific information associated with an
object file.

noft Options

nld and noft Manual—520384-003

5-2

LISTCOM PILERS or LC on

page 5-23

Lists version information about the nat iv e compiler
components and nld utility used to create an object file.

LISTOPTIMIZE or LO

on

page 5-26

Lists procedures based on the optimization level.

LISTPROC or LP

on page 5-27 Lists procedu res and subp roc edures.

LISTSOURCE or LS

on

page 5-29

Lists the source files in an object file.

LISTSRLEXPORTS o r LLE

on

page 5-30

Lists information about the symbols exported by a
shared run-time libr ary (S R L).

LISTSRLF I XUPS or LLF

on

page 5-30

Lists the names of the SRLs to which the unresolved
symbols in a client object file have been “fixed up.”

LISTSRLI N F O or LLI

on

page 5-31

Lists the SRLs linked into an object file.

LISTUNREFERENCED or LUR

on page 5-32

Lists the undefined and unreferenced symbols an object
file.

LISTUN R ESOLVED o r LU

on

page 5-35

Lists the unresolved symbols in an object file.

LOG

on page 5-38 Writes a copy of the current noft session’s input and

output t o a file.

OBEY

on page 5-39 Directs noft to r ead from a specif ied command f ile.

OUT

on page 5-39 Does on e of t he f ollowing:

•

Redirects output to a specified file (the output file)

•

Redirects output to the standard output file

•

Displays the name of the current output file

QUIT or Q

on page 5-40 Stops the noft process.

RESET

on page 5-41 Resets one or more noft target object file parameters

previous ly s pecified with a th e SET option to their
default values.

Table 5-1. noft Flag Summa r y (page 2 of 3)

Flag De scription

noft Options

nld and noft Manual—520384-003

5-3

Break Key

Break Key

The break key Terminates the output of the current option and, if noft is running from
the command line, terminates the noft program itself.

SET on page 5 -42 Sets one o r m ore of the follow ing:

•

Case sensitivity of noft

•

Object file format

•

Number of command lines in memory available to
the FC or HISTORY option (use only in an
interactive session)

•

Number of command lines displayed with the
HISTORY option (use only in an interactive session)

•

Number of lines of output to display before pausing
so that an area of output does not scro ll out of the
terminal or em ulator displ ay m em ory

•

Name an d type of log file

•

Name an d type of output f ile

•

Scope of noft options to a single procedure or
subprocedure

•

Scope of noft options to a single source file

•

Sorting order of the output

SHOW

on page 5-47 Displays the current values of the noft program

environment parameters and the target object file
parameters.

SYSTEM or VOLUME

on

page 5-48

Specifies the de f ault node, volume, and subv olume
names used to resolve partially-qualified Guardian
filenames. (Use only in the Guardian environment.)

XREFPROC or XP

on page 5-49 Displays a c ross referenc e listing of proc edures.

Table 5-1. noft Flag Summa r y (page 3 of 3)

Flag De scription

noft Options

nld and noft Manual—520384-003

5-4

! (Exclama t ion Point)

! (Exclamation Point)

The ! (exclamation point) option executes a previously executed command.

history-number

is the history-buffer number of the command to be re-executed.

-history-offset

is a negative offset from the command that history-number represents. The

immediately preceding command is -1.

text

is a string of characters. If you provide text instead of history-number or

-history-offset, the ! option executes the most recently executed command

that begins with the string text.
The history-buffer number of the command specified by history-number,

-history-offset, or text must be less than or equal to the number of commands
in the history buffer, which is determined by SET HISTORYBUFFER (see SET on
page 5-42, particularly Example 5-8 on page 5-19). The default size of the history
buffer is 50 commands.

If you do not specify history-number, -history-offset, or text, the ! option
executes the previous command.

Note. This opt ion works only in an interactive ses s ion.

! [ history-number | -history-offset | text ]

noft Options

nld and noft Manual—520384-003

5-5

CD

CD

The CD option changes the current working directory, which noft searches for relative
pathnames.

pathname

is the OSS directory pathname of the directory that is to become the current

working directory. The maximum size of pathname is 255 characters. The default

pathname is the star tup di rectory.

COMMENT

The COMMENT option imbeds comments in noft command files.

text

is a string of characters (a comment).
Considerations:

•

If you use the COMMENT option in a line cont aini ng oth er opt ions, COMMENT must be

the last option on the line.

•

To continue COMMENT text over more than one line, start each successive line with

the COMMENT option.

Note. OSS envi ronment only. Similar Guardian commands are SYSTEM or VOLUME on
page 5-48.

CD [ pathname ]

Note. The noft utility do es not verify the va lidity of the spec if ied pathname . noft

provides verification only when trying to open an object or source file.

Example 5-1. CD Option

noft> cd
Current Path : /lt1/abcdef/tests/show/

COMMENT [ text ]

noft Options

nld and noft Manual—520384-003

5-6

DUMPADDRESS or DA

DUMPADDRESS or DA

The DUMPADDRESS option displays code and data from a virtual address inside an
object file’s memory space.

Because all sections in linkfiles start at zero, use DUMPOFFSET or DO on page 5-8 to
display any section other than the text section.

start-address

is the starting virtual address in hexadecimal format.

range-specifier

is the amount of information to display:

{ TO end-address | FOR { number { BYTES | B | WORDS | W } | * }}

end-address

is an ending virtual address in hexadecimal format.

number

is the number of bytes or words to display.

*

displays information to the end of the code or data section.

Considerations:

•

The range of addresses must be entirely within one code or data section.

•

The address of a code section is rounded up to a whole number of words.

•

If an address range begins in a code or data section and ends outside the
section, the output stops at the end of the section and noft emits an error
message.

format-specifier

specifies how the information is to be formatted. format-specifier is one of

the following:

{ ASCII | A }

displays portions of the object file in ASCII format.

[ DUMPADDRESS | DA ] start-address [ range-specifier ]
[ IN format-specifier ]

noft Options

nld and noft Manual—520384-003

5-7

DUMPADDRESS or DA

{ DECIMAL | D }

displays portions of the object file in decimal format.

{ HEX | H }

displays portions of the object file in hexadecimal format.

{ ICODE | IC }

displays portions of the object file in disassembled program code. This is the
default.

{ INNERLIST | IN }

displays portions of the object file in disassembled program code and displays
the source code interspersed with the code. This option can only be used for
displaying text.

{ OCTAL | O }

displays portions of the object file in octal format.

If you do not specify the format with the DUMPADDRESS option, the formatting is

controlled by the SET FORMAT option (see SET on page 5-42).

Example 5-2. DUMPADDRESS Option

noft> dumpaddress 0x700005ac for 10 words
******** Readable Dump Of Range 0x700005ac To 0x700005d4 ********

Procedure Src Line Address Long Word Instructions

------------------------------------------------------------------------­ [rollem 87000] 0x700005ac 0x0d81015c jal 0x76040570

-[rollem 83000] 0x700005b0 0xafb00014 sw s0,0x14(sp)
[rollem 87000] 0x700005b4 0x00408025 move s0,v0
[rollem 87000] 0x700005b8 0x24010006 li at,0x6
[rollem 87000] 0x700005bc 0x0201001b divu s0,at
[rollem 87000] 0x700005c0 0x00007010 mfhi t6
[rollem 87000] 0x700005c4 0x25cf0001 addiu t7,t6,0x1
[rollem 88000] 0x700005c8 0x0d81015c jal 0x76040570

-[rollem 87000] 0x700005cc 0xafaf002c sw t7,0x2c(sp)
[rollem 88000] 0x700005d0 0x00408825 move s1,v0

noft Options

nld and noft Manual—520384-003

5-8

DUMPOFFSET or DO

DUMPOFFSET or DO

The DUMPOFFSET option displays code and dat a from a physical offset within an object
file.

start-address

is the starting virtual address in hexadecimal format.

range-specifier

is the amount of information to display:

{ TO end-address | FOR { number { BYTES | B | WORDS | W } | * }}

end-address

is an ending virtual address in hexadecimal format.

number

is the number of bytes or words to display.

*

displays information to the end of the code or data section.

Considerations:

•

The offset address of a code section is rounded up to a whole number of
words.

•

If the offset range ends outside of the file, the output stops at the end of the file
and noft emits an error message.

format-specifier

specifies how the information is to be formatted. format-specifier is one of

the following:

{ ASCII | A }

displays portions of the object file in ASCII format.

{ DECIMAL | D }

displays portions of the object file in decimal format.

{ HEX | H }

displays portions of the object file in hexadecimal format.

{ DUMPOFFSET | DO } start-address [range-specifier]
[IN format-specifier]

noft Options

nld and noft Manual—520384-003

5-9

DUMPOFFSET or DO

{ ICODE | IC }

displays portions of the object file in disassembled program code. This is the
default.

{ INNERLIST | IN }

displays portions of the object file in disassembled program code and displays
the source code interspersed with the code. This option can only be used for
displaying text.

{ OCTAL | O }

displays portions of the object file in octal format.

If you do not specify the format with the DUMPOFFSET option, the formatting is

controlled by the SET FORMAT option (see SET on page 5-42).

Example 5-3. DUMPOFFSE T Option

noft> dumpoffset 0x00000390 for 20 bytes
***** Readable Dump Of Offset 0x00000390 To 0x000003a4 *****

0x00000390 0x27bdffe0 addiu sp,sp,0xffffffe0
0x00000394 0xafbf001c sw ra,0x1c(sp)
0x00000398 0x3c0e0800 lui t6,0x800
0x0000039c 0x3c0f5800 lui t7,0x5800
0x000003a0 0x25ef0048 addiu t7,t7,0x48

noft Options

nld and noft Manual—520384-003

5-10

DUMPPROC or DP

DUMPPROC or DP

The DUMPPROC option displays the contents of a procedure or part of a procedure.

proc-spec

specifies the procedure name. Procedure names are case sensitive in C and C++

but not in other languages. procedure-spec is one of the following:

proc-name

limits the scope to the specified procedure and subprocedures.

proc-name.subproc-name

limits the scope to the specified subprocedure.

subproc-name

limits the scope to the specified subprocedure.

proc-num

specifies the procedure number. This number specifies the ordering in the object

file’s procedure table. Use LISTPROC or LP on page 5-27 to list each procedure

number.

offset

is the number of bytes beyond the starting virtual address of the procedure (in

hexadecimal format).

range-specifier

is the amount of information to display:

{ TO end-address | FOR { number { BYTES | B | WORDS | W } | * }}

end-address

is an ending virtual address in hexadecimal format.

number

is the number of bytes or words to display.

*

displays information to the end of the code or data section.

{ DUMPPROC | DP } { proc-spec | proc-num }
[ { offset } [range-specifier]] [IN format-specifier]