DLL Programmer’s Guide for TNS/E Systems Abstract This guide describes how application programmers can use the DLL facilities provided on TNS/E systems and recommends good practices in using them. Product Version T9050 at H06.01 Supported Release Version Updates (RVUs) This publication supports J06.03 and subsequent J-series RVUs and H06.03 and subsequent H-series RVUs, until otherwise indicated by its replacement publications.
Document History Part Number Product Version 527252-002 527252-003 527252-004 527252-005 527252-006 Published T9050 T9050 T9050 February 2005 T9050 T9050 August 2010 May 2005 July 2005 April 2012
Legal Notices Copyright 2012 Hewlett-Packard Development Company L.P. Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice.
DLL Programmer’s Guide for TNS/E Systems Glossary Index Figures Tables Legal Notices What’s New in This Manual vii Manual Information vii New and Changed Information vii About This Manual ix Purpose of This Manual ix Who Should Read This Manual ix How This Manual Is Organized ix Related Reading ix Notation Conventions x HP Encourages Your Comments xiv 1.
2. Essential DLL Facility Controls Contents 2.
3. Dynamic Use of DLLs Contents 3.
5. Advanced DLL Facility Controls (continued) Contents 5.
Tables Contents Tables Table 4-1. Table A-1.
Contents DLL Programmer’s Guide for TNS/E Systems—527252-006 vi
What’s New in This Manual Manual Information DLL Programmer’s Guide for TNS/E Systems Abstract This guide describes how application programmers can use the DLL facilities provided on TNS/E systems and recommends good practices in using them. Product Version T9050 at H06.01 Supported Release Version Updates (RVUs) This publication supports J06.03 and subsequent J-series RVUs and H06.03 and subsequent H-series RVUs, until otherwise indicated by its replacement publications.
What’s New in This Manual Changes to the H06.21/J06.10 manual: Added the term Neutral loadfile. on page Glossary-4. Changes to the H06.21/J06.10 manual: Added new section Special initialization and termination procedures on page 5-5. Add a note on systype on page 5-8. Add a note on data2protected attribute on page A-4. Added c99 compiler information throughout the manual, wherever applicable.
About This Manual Purpose of This Manual The DLL Programmer’s Guide For TNS/E Systems is intended as an introduction to the process of creating and using Dynamic-Link Libraries (DLLs) on TNS/E H-series systems. Who Should Read This Manual Applications and System Programmers who want to create or use DLLs. How This Manual Is Organized This manual consists of the following sections: Section 1, DLLs on a TNS/E System.
Notation Conventions About This Manual eNOFT Manual. This contains information on examining PIC object files on H-series systems. TACL Reference Manual. This contains information on loadfiles in processes and processes using loadfiles. Guardian Procedure Calls Reference Manual. Guardian Procedure Errors and Messages Manual.
General Syntax Notation About This Manual computer type. Computer type letters within text indicate C and Open System Services (OSS) keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: myfile.c italic computer type. Italic computer type letters within text indicate C and Open System Services (OSS) variable items that you supply. Items not enclosed in brackets are required. For example: pathname [ ] Brackets.
General Syntax Notation About This Manual Punctuation. Parentheses, commas, semicolons, and other symbols not previously described must be typed as shown. For example: error := NEXTFILENAME ( file-name ) ; LISTOPENS SU $process-name.#su-name Quotation marks around a symbol such as a bracket or brace indicate the symbol is a required character that you must type as shown. For example: "[" repetition-constant-list "]" Item Spacing.
Notation for Messages About This Manual !o:i. In procedure calls, in TAL or PTAL, the !o:i notation follows an output buffer parameter that has a corresponding input parameter specifying the maximum length of the output buffer in bytes. For example: error := FILE_GETINFO_ ( filenum , [ filename:maxlen ] ) ; !i !o:i Note that some interfaces count the pair as a single parameter for error-reporting purposes, even though they constitute two separate parameters, and must be so expressed in C or C++.
Change Bar Notation About This Manual either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: obj-type obj-name state changed to state, caused by { Object | Operator | Service } process-name State changed from old-objstate to objstate { Operator Request. } { Unknown. } | Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces.
1 DLLs on a TNS/E System This section explains the TNS/E DLL (dynamic-link library) facility – what DLLs are, how they work, how they can be used, and the basic workings of the tools that create them. This facility comprises the linker (eld), the loader (rld), and the portions of the HP NonStop™ operating system used in loading libraries. The facility runs in either the OSS or Guardian environments, and on auxiliary Windows systems you can construct, but not load, TNS/E applications that use DLLs.
Libraries and Symbols DLLs on a TNS/E System A loadfile exports a symbol when it defines a symbol that can be used by another loadfile. A loadfile imports a needed symbol when that symbol reference in the program or DLL is or will be set to the value (address) of a symbol of the same name exported by another loadfile. Thus, in Figure 1-1, Library K exports Joe and, after H is loaded, H imports Joe.
DLLs on a TNS/E System Position-Independent Code (PIC) in TNS/E Position-Independent Code (PIC) in TNS/E All code on a TNS/E system is position-independent. Code that can be relocated in virtual memory at load time without alteration is called position-independent code (PIC). If you use DLLs in your application, your program and these DLLs must be PIC.
Why Dynamically Linked Libraries? DLLs on a TNS/E System Figure 1-2. An Application Made Up Of a Program And The DLLs It Needs Program DLL A DLL D DLL B DLL C DLL E DLL F DLL G VST012.vsd Why Dynamically Linked Libraries? For statically linked programs, you must copy all shared libraries into your own programs; thus, complete copies of these libraries appear in all the programs that use them, and each copy consumes main memory and disk space.
DLLs on a TNS/E System Building and Loading Programs and Libraries A new version of a DLL can be introduced without having to alter a program or DLL that references it, even though the location of the referenced sites has changed. This gives you great freedom to change a DLL. A program and the DLLs loaded with it at process creation time can access each other’s functions and data by simply referencing their symbolic names.
Compilers DLLs on a TNS/E System Figure 1-3. Simplified Code Generation and Load Processes Source Compiler Linkfile Linkfile Linkfile Linker Loadfile Loadfile Loadfile { A program and libraries Loader Executable load image VST013.vsd Compilers The TNS/E compilers translate source input into a linkfile.
DLLs on a TNS/E System Loading You invoke the linker by a single command, eld, and control it by items you enter in its command stream, which comprises the options, file names, and parameters that modify the eld command. Later, the loader brings together programs with their required libraries in structures like that shown in Figure 1-2 on page 1-4.
DLLs on a TNS/E System Finding the Needed Libraries See Section 3, Dynamic Use of DLLs for further details. After the program and the initially loaded libraries are running, the program or a loaded DLL can also call on the loader to dynamically load yet other DLLs. References by the newly loaded DLLs are resolved among already loaded loadfiles, and subsequent function calls can retrieve symbols offered by the newly loaded DLLs.
The TNS/E Library Facility DLLs on a TNS/E System Figure 1-4. Loadfiles and Their libLists (To Create the Structure in Figure 1-2) Code and Data libList Program Lib A Lib B Lib C DLL A DLL D Lib D Lib E Lib G Lib G DLL B DLL E Lib F Lib G DLL C Lib F Lib F VST014.vsd For the loadfiles in Figure 1-4: The program indirectly references D, E, F, and G, so these libraries do not appear in the program’s libList. The program’s loadList comprises all the libraries shown in the figure.
DLLs on a TNS/E System The Public Library Registry TNS/E compiler run-time libraries. Libraries that support connections to TNS/E communication facilities. Certain TNS/E tools, utilities, and the loader library (rld). TNS/E compilers generate needed linkages from PIC programs and DLLs to the compilers’ run-time libraries. In Figure 1-2 on page 1-4, DLLs F and G might instead be public DLLs, because they refer to no PIC loadfiles.
DLLs on a TNS/E System Linkfiles and Archives DSM/SCM creates an initial registry file, listing all the public DLLs by name. This is an edit file (filecode 101). Use DSM/SCM to add your public DLLs to those provided by HP. Entries to the file consist of a series of statements. The dll statement describes a public DLL. In its simplest form, it is just a name, for example: dll file ztestdll; Here is another example; it contains the license attribute. A licensed DLL is one that contains privileged code.
DLLs on a TNS/E System Other Loader Operations Semi-globalized — A semi-globalized loadfile uses its own definition for any of its symbol references when it offers such a definition, but imports other definitions from the program it is loaded with and any loadfile in the program’s loadList. In any case, if the symbol to be imported is defined only once in the collection of loadfile candidates to supply imported symbols, that symbol is used to resolve your loadfile’s need.
DLLs on a TNS/E System User Library An important advantage of dynamically loaded DLLs is that their names and their symbols need not be known when the program is constructed. Using this facility, you can add to an existing application a new DLL that provides new functionality without even restarting the application. You do not need to load infrequently used DLLs when the application is loaded. Instead, you can load and use these DLLs when required and unload them when they are no longer needed.
User Library DLLs on a TNS/E System Figure 1-5. Loadfiles of Figure 1-4 with a User Lib and Its Library Added Code and Data libList Program DLL D Lib D Lib E Lib G Lib G Lib A Lib B Lib C User Library (DLL) DLL A DLL B DLL E Lib F Lib G DLL C Lib F Lib H Lib F Lib H VST015.vsd A user library can also be specified at run time: In Guardian, the run-option lib can specify the fully qualified name of the user library: /lib $vol.subvol.
2 Essential DLL Facility Controls You control the TNS/E DLL facility by using the linker and the loader options, many of which normally run using automatic defaults. This section explains the linker’s most commonly used controls, but Advanced DLL Facility Controls on page 5-1 tells you how to get more precise control over the process and its results.
Essential DLL Facility Controls Option Types File name – A name of a file, which may or may not be an argument of an option. In this document, a file name in the command stream that is not a part of an option is said to be directly inserted in the command stream. Parameter – A non-file-name argument of an option The command stream comprises all the tokens that modify an eld command; these are processed in the order they appear in the command stream.
Essential DLL Facility Controls Specifying the Linker’s Output Specifying the Linker’s Output By default, the linker merges linkfiles to produce loadfiles. Following the eld command, you should list the names of the linkfiles to be combined, as illustrated in this command-stream fragment: eld linkfile1 linkfile2 where linkfile1 and linkfile2 are names of linkfiles to be combined in the link. Choosing the Output File The output file is where the linker stores the loadfile that results from a link.
Essential DLL Facility Controls File-Name Qualification You also have three ways to give the DLL and its output file the same name: The -o option, when used by itself, assigns to the internal DLL name as well as the file. When using the -o option and is a qualified file name, the DLL name is obtained by truncating to remove the path or subvolume definition and yield the corresponding unqualified name. See File-Name Qualification below.
Essential DLL Facility Controls File-Name Qualification OSS - If it is "absolute" (begins with a /), take it as is; otherwise append it to the current working directory. Win32 - As above, except for drive: and \ issues. The distinctions become more important for file names specified by the -lib (-l) option. In this case, only unqualified names are subject to searching through the list of paths. Partially or fully qualified names are treated as above.
At a Glance: Controlling Linker Output When Producing a Loadfile Essential DLL Facility Controls When it comes to parameters that are symbol names, no such rules apply. An equal sign at the start of a symbol name has no special significance to the linker. There is a special case. In the case of the -libname (or -set libname, or -change libname) option, usually, it is an error if the parameter is not exactly of the form $a.b.c.
Specifying Which Inputs Go into a Link Essential DLL Facility Controls To: Action: Specify the name of the file in which to store the result Assign the file name with a -o option Name the resulting DLL differently from the output file Assign the DLL name with the -dllname option and the file name with a -o option. Simultaneously give the same name to the output DLL and the file it is stored in Assign the name with a -o option and do not use a -dllname option, or vice versa.
Essential DLL Facility Controls Linkfile Inputs -all and -none are toggle options you can insert multiple times in the command stream to set the mode for archives that are subsequently specified in the command stream. You can also insert the same archive more than once in the command stream. At the beginning of the command stream, the default mode is -none.
Essential DLL Facility Controls Library Inputs While the archive is open (when -none is in effect), the linker searches for symbols that are unresolved in the loadfiles seen so far, or specified by the -u option, or unresolved in linkfiles selected from the archive. The archive can have indirectly needed linkfiles. The linker finds them regardless of their order.
Essential DLL Facility Controls Files the Linker Opens Normally If the linker is given a qualified file name inserted directly in the command stream, it opens the file in the normal way for the linker host platform. If the linker is given an unqualified file name inserted directly in the command stream, it opens a file of that name in the current directory or subvolume.
Essential DLL Facility Controls Libraries the Linker Searches For and Opens appropriate to the linker platform and then attempt to open the resulting file. This is described in Augmenting Library Names Automatically in Searches on page 5-2. A -lib option cannot specify any of the primary linkfiles in a link; these must be inserted separately in the command stream as qualified file names or unqualified names if the files are in the current directory.
Essential DLL Facility Controls Specifying a User Library for a Program For Guardian, unless the -b static option is in effect, the linker searches in $SYSTEM.ZDLL. For Win 32, the linker does not search in any standard places. You can have the linker skip steps 2 and 4 above by inserting the -nostdlib option or its synonym -no_stdlib.In this event, the linker will search for libraries in places specified by -first_L or -libvol options.
Essential DLL Facility Controls At a Glance: Files the Linker Brings into a Link At a Glance: Files the Linker Brings into a Link To incorporate in a link: Action: A linkfile, archive, or library to open normally Insert its qualified file name directly in the command stream An archive or library to search for and open Insert its unqualified file name in a -lib option Compile-Time Control of Export and Import The TNS/E C and C++ compilers provide facilities to specify export and import controls at co
Essential DLL Facility Controls Your Loadfile’s Exported Symbols linkfile or loadfile. However, the compilation of the module that implements class foo can contain #define export_foo export$ ahead of the #include directive for this header file. As a result, this compilation will define all the symbols associated with class foo, and mark them offered for export.
How to Make Your Loadfile Re-Export Symbols of Other DLLs Essential DLL Facility Controls How to Make Your Loadfile Re-Export Symbols of Other DLLs When you link your DLL, you can make it re-export the exported symbols of any library in its libList. To do this you insert the -reexport option, after which you insert directly or in a -lib option the libraries which are to be re-exported.
Some Examples Using Re-Exportation Essential DLL Facility Controls 2. Recompile and relink the new sources, and give one resulting loadfile (say the one that exports Alpha and Beta) a new name, Y. Give the other loadfile the old name, D. See Naming DLLs on page 2-3. 3. Set up D to re-export Y. The result is shown in Figure 2-2 on page 2-16, where the dashed lines through D indicate re-exportation.
Things to Consider about the Loader Essential DLL Facility Controls Figure 2-3. the New Symbol, Gamma, With New Function (Shaded), Replaces the Old Gamma. Alpha Alpha Beta Beta Gamma Gamma DLL D (new) X Gamma DLL Y (old D) DLL A VST023.vsd Because the search order for the linker and loader comes to D before Y (See Finding Symbol Definitions on page 4-1), D’s Gamma masks Y’s. So without any change to the users, all of those that formerly used old D’s Gamma will now get new D’s Gamma.
Essential DLL Facility Controls The Link-Time-Defined Search Path of the Loader 2. The public libraries. 3. The directory or subvolume specified in a -RLD_L option in the linker’s command stream, where is a path or paths to a specified directory or subvolume. The -RLD_L option is not required but when used, is repeatable with different path strings. 4.
Essential DLL Facility Controls Unresolved Symbols at Load Time The -RLD_first_L option is rarely necessary, because the public libraries have unique names that should not overlap those supplied by the user or other agencies. It is more efficient to have the public libraries first on the path search list at load time, because the set of public libraries can be searched very quickly using a table in memory.
Essential DLL Facility Controls C++ Dialect 1. If the -set floattype option is inserted, the linker sets the floatingpoint type of the output loadfile to , where can be ieee, tandem, or neutral. 2. If the -set floattype option is not inserted, then if the input linkfiles do not contain a mixture of both ieee and tandem floating-point types, the linker sets the floating-point type of the output loadfile to the one that is represented.
Essential DLL Facility Controls C++ Dialect Checking the C++ Dialect of Linkfiles That Go into a Link The linker checks for consistency of C++ dialect among all input linkfiles. If any linkfiles from C++ compilations differ in C++ dialect, the linker terminates in error. Setting the C++ Dialect of a Loadfile Being Linked The C++ dialect of the loadfile being linked is determined in one of two ways. 1.
Essential DLL Facility Controls Execution-Target System Type SQL/MX Restriction Public DLLs that support SQL/MX have cppdialect = version2. Therefore, SQL/MX clients cannot yet use C++ version3. Execution-Target System Type The linker sets a system-type attribute in the output loadfile to the following default values. If the linker is hosted on a PC, the default is OSS.
Essential DLL Facility Controls Linker and Loader Errors 4. By default, the linker uses only the linkfiles from an archive that resolve currently unresolved symbols. [Selecting Linkfiles from Archives on page 2-7] 5. By default, the linker exports those symbols for which your compiler sets the xport bit in the external symbol table. [Controlling Which Symbols Your Loadfile Exports on page 5-5] 6. The linker builds a loadfile that, by default, re-exports no other DLLs.
Essential DLL Facility Controls DLL Programmer’s Guide for TNS/E Systems—527252-006 2-24 Linker and Loader Errors
3 Dynamic Use of DLLs An important attribute of the DLL facility is that a running PIC program or DLL can load and open a previously not-loaded DLL and gain access to the symbols it offers. DLLs invoked this way are called dynamically loaded DLLs. One advantage of dynamically loading a DLL is that its name need not be known when the program is constructed; instead, you can add this new DLL to an existing application without even restarting the application.
Opening a DLL from a Running Loadfile (dlopen) Dynamic Use of DLLs declared in a header file called dlfcn.h and defined in the loader’s library. Therefore, any C or C++ source file that uses these functions must contain the following: #include The same functions have pTAL external declarations in a file named hldfcn. Both header files also define parameter types and constants for using with these functions. These functions are implemented in the public library ZRLDDLL.
dlopen’s Mode Parameter Values Dynamic Use of DLLs *object_pathname is either zero (NULL) or a pointer to the null-terminated file name (string) of the DLL to open and load, which is called herein the dlopen target. mode is an enumeration of options that control symbol resolution and loading, as described in dlopen’s Mode Parameter Values below.
dlopen’s Mode Parameter Values Dynamic Use of DLLs RTLD_LAZY This option is accepted to provide compatibility for UNIX, but is treated the same as RTLD_NOW. RTLD_GLOBAL This option specifies that the newly loaded DLLs should be added to the cumulative loadList, i.e. new libraries are added to the global set, which consists of the program and libraries loaded initially by rld. This is the default. RTLD_LOCAL This option is accepted to provide compatibility for UNIX, but is treated the same as RTLD_GLOBAL.
Returned Value of dlopen Dynamic Use of DLLs Each valid combination can be combined with the verbosity level, via RTLD_VERBOSE (verbosity_level) to create the mode parameter. Returned Value of dlopen dlopen() returns a handle (value) for the calling process to use in subsequent calls to the dlopen target. This handle is not usable in any other way; in particular, it is not an address.
Returned Values of dlsym Dynamic Use of DLLs A handle returned by a previous dlopen call and not invalidated by dlclose(). *symbol_name A pointer to the null-terminated name (string) of a symbol to be accessed in the specified loadfile. Returned Values of dlsym Each dlsym() call returns the address of a specified symbol. You can use the returned address by storing it as a pointer of a type appropriate for the function or datum designated by the symbol.
Returned Values of dlclose Dynamic Use of DLLs dlclose invalidates the handle and makes it unavailable for any other call that uses that handle. If the specified handle is the last outstanding one for the referenced DLL and if that DLL was dynamically loaded (by dlopen), the DLL is also unloaded. The following is the parameter of a dlclose call: dlopen_handle is a handle previously returned by a dlopen call.
Error Encoding: dlresultcode Dynamic Use of DLLs There has never been a call to dlopen, dlclose, or dlsym in this process. Otherwise, dlerror returns a pointer to a buffer that contains a null-terminated character string containing only displayable characters and no trailing newline character.
Thread Considerations Dynamic Use of DLLs Calling dlresultcode() does not reset the error code. dlerror() and dlresultcode() can be called in either order; neither affects the value returned by the other. dlresultcode() is an HP NonStop operating system addition to the conventional set of dynamic loading functions. Thread Considerations The loader is not aware of threads that may be used in a multi-threaded application.
Dynamic Use of DLLs Using Dynamically Loaded DLLs to Extend an Application More elaborate conventions can have the DLL export a canonical "master" function or data structure that describes the functions or data available in this library. The application uses dlsym() to locate the "master" symbol.
4 Finding Symbol Definitions This section describes how the linker and loader resolve symbol references, including cases when multiple definitions are available for the same symbol name. Figure 4-1 on page 4-1 shows the evolution of code from source to linkfile to loadfile to executable PIC load image. At the linkfile and loadfile stages, these code objects can be brought together so they can exchange services and data.
Finding Symbol Definitions The loadList The linker or loader creates the loadList for a loadfile using the following algorithm: 1. [Initialize] To an empty loadList add the name of the designated file, and set a pointer referring to this entry, making it the currently referenced loadfile. 2. If the designated file is the program and it has a user library, add the library name to the loadList. 3.
Global Scope, Import and Export Finding Symbol Definitions Figure 4-2. Development of the Globalized SearchList for the Program and Libraries based on Figure 1-5 on page 1-14 Algorithm step: 1st LoopRun 2nd LoopRun 4 5 Program Program UL A UL A B B C C Program Program UL UL A B A B C C D 3rd LoopRun 4th LoopRun 5th (last) LoopRun Program Program UL A UL A B B C D C D Program Program UL A UL A B B C D C D Program Program UL UL A A B C B C D D VST043.
Finding Symbol Definitions Global Scope, Import and Export and libraries). Furthermore, the application of these concepts differs from one source language to another. In the C language, items declared within a function are local to that function and are undefined (invisible) elsewhere. Items declared outside any function have global scope and are visible in any function that does not hide that declaration with a local one of the same name.
Finding Symbol Definitions Import Controls and SearchLists With the linker, you can export individual symbols, or you can cause all global symbols in your loadfile to be exported, and then you can choose which symbols not to export. See Controlling Which Symbols Your Loadfile Exports on page 5-5. Import Controls and SearchLists Just as you have control over the symbol definitions your loadfile offers for export, you can control the sources from which your loadfile can import symbol definitions.
Finding Symbol Definitions The SearchList for a Localized Loadfile linking a localized loadfile and the loader uses when loading it. The algorithm is illustrated in the example that comes after it. 1. [Initialize] To an empty searchList add the name of the localized loadfile being linked and set a reference pointer pointing to this entry, making it the currently referenced loadfile. 2. If the referenced loadfile is a program that has a user library, add the user library’s name to the searchList. 3.
The SearchList for a Localized Loadfile Finding Symbol Definitions Figure 4-3. The Loadfiles of Figure 1-5, Now Showing the Use and Availability of the Global Symbol xray Exports xray DLL A DLL D Lib D Lib E Lib G Imports xray Code and Data libList Program Lib A Lib B Lib C Lib G DLL B DLL E Lib F Lib G Exports xray User Library (DLL) Lib H DLL C Lib F Lib F Lib H VST042.vsd The final searchList is shown at the bottom of Figure 4-4.
Finding Symbol Definitions The SearchList for a Globalized Loadfile The SearchList for a Globalized Loadfile For a loadfile with globalized import, the linker's searchList is just its loadList; the loader's searchList is the loadList of the program. (For dynamic loads, that is the operating load set, also called the cumulative loadList of the program.
The SearchList for a Globalized Loadfile Finding Symbol Definitions Figure 4-4. Development of the Globalized SearchList for the Program and Libraries in Figure 4-3 Algorithm step: 1st LoopRun 4 5 Program Program UL UL A B A B C C H 2nd LoopRun Program Program UL UL A B A B C C H H D E 3rd LoopRun Program UL Program UL A A B C B C H H D E D E F Program UL A B C H 9th (last) LoopRun D E F G VST044.
The SearchList for a Globalized Loadfile Finding Symbol Definitions on page 4-10, the programmer of globalized DLL B links it to another globalized library, called F, that exports the symbol definition of john that B should use. Thus, there appears to be no ambiguity, and the resolution of john should be simple. But, because B is globalized, the loader sees it differently. Figure 4-5. Localized and Globalized Symbol Resolution Exports john Lib F DLL B Lib F DLL B as it was linked.
Finding Symbol Definitions The SearchList for a Semi-Globalized Loadfile Perhaps more surprising, if a DLL references its own global symbol definition, one might think that this definition would always be used to satisfy this DLL. However, as we saw earlier in Ambiguity Example 1 on page 4-8, the loader can preempt the linker’s setting and decide to import that symbol. So, if a DLL is globalized, any of its references might be satisfied by a symbol of the same name in some other loadfile.
C++ Considerations: Globalized (Gblzd) Symbols Finding Symbol Definitions the loadfile itself. That range comprises the loadfile’s LibList, the loadfiles that those loadfiles re-export, and so on. Table 4-1.
Finding Symbol Definitions System Library and Millicode System Library and Millicode The TNS/E system and millicode libraries are implicitly attached to the end of every searchList and cannot be mentioned in the command stream. So, if the loader does not find a needed symbol definition in the loadfiles in the searchList, it will automatically look for one in the system and millicode libraries. Symbol Resolution at a Glance Globalized symbols defined in C++ receive special handling, described above.
Example: Intercepting an Exported Symbol Finding Symbol Definitions Figure 4-6. Intercepting a Call to Library D Alpha Alpha Beta Beta Gamma Gamma Gamma DLL A Joe Joe Gamma Library D DLL X DLL Y VST046.vsd The symbol Gamma, provided by the existing Library D, is intercepted for selected calling loadfiles (including DLL A). These selected loadfiles must be relinked to put DLL X in their libLists and remove Library D. Hence, their Gamma references are bound to the definition in DLL X.
5 Advanced DLL Facility Controls This section tells how you can manually override and extend previously described linker and loader defaults and options to meet special needs.
Advanced DLL Facility Controls Augmenting Library Names Automatically in Searches the linker can only be looking for archives, and even if -allow_missing_libs has been inserted, the linker will terminate in error if it doesn’t find the specified archive file. Augmenting Library Names Automatically in Searches By convention in OSS and Windows, names for DLLs and archives have a common prefix, lib, and have distinguishing suffixes (filename extensions), .so for DLLs and .a for archives.
Advanced DLL Facility Controls Making the Linker Look for Unresolved Symbols The linker can determine that they are the same size and that their initial values (if any) are the same. Otherwise, the linker treats multiple definitions of a data item in input linkfiles as an error. Procedure Definitions Multiple procedure definitions of the same symbol are permitted when the compiler generates and appropriately labels the duplicates.
Advanced DLL Facility Controls Linker Output Controls loadfile being linked is globalized or semi-globalized, the linker searches for libraries and their symbols following a searchList that is identical to this loadfile’s loadList. Until the linker finds a library that offers a symbol that the output loadfile needs, it considers that symbol unresolved.
Advanced DLL Facility Controls Controlling Which Symbols Your Loadfile Exports Controlling Which Symbols Your Loadfile Exports Symbols offered for export are those made available to other loadfiles. By default, the linker offers for export those symbols designated by the compiler to be exported.
Advanced DLL Facility Controls C++ Mangled Symbol Names iniTerm lists corresponding to these procedures, and places pointers (ctors and dtors addresses) to them in the tandeminfo segment of the object file. ___INIT__ and __TERM__ Apart from the procedures from runtime-library, the user program itself might contain procedures with these names (for example, __INIT__< name>).
Advanced DLL Facility Controls How to Set Run-Time Attributes of Your Loadfile sets the floating-point type of the output loadfile. Possible values are ieee, tandem, and neutral. See Setting the Floating-Point Type of a Loadfile Being Linked on page 2-19. heap_max has a numeric (hexadecimal) value with a default of zero (0). highpin has possible values of on and off. The default is on. highrequestors has possible values of on and off. The default is on. incomplete has only one possible value, on.
Advanced DLL Facility Controls Controlling the Load Image of DLLs bound to this definition and either a message is put out if warn is set or no message is put out if ignore is set. By default, the loader finds this function defined in the system library. If invoked, it generates a non-deferrable SIGILL signal.
Advanced DLL Facility Controls Using the Linker to Change an Existing Loadfile -d address this is a hexadecimal number that sets the starting address of the data segment. In both cases, the linker rounds up address to a virtual memory page boundary. If -t, but not -d, is inserted, then -t specifies the starting address of the entire contiguous DLL. By inserting -d, you can cause the DLL to load in two separate regions.
Advanced DLL Facility Controls Link-Time Operation You can insert multiple -change options, where each must be followed by the name of the affected loadfile, even if the loadfile is the same in each case. These options are executed one at a time in the order inserted. Your user ID must have write access to the file to execute the -change option on it.
Advanced DLL Facility Controls Naming Intermediate Linker Output Files OSS The c89 or c99 compiler will run the linker for each module it compiles, unless the -c option is present. It is somewhat more flexible in allowing you to specify linker commands to the compiler: The -L and -l options are passed straight through, with their arguments. Several other linker options are recognized in -W form; run c89 or c99 with no command input to see a list.
Controlling What Checks the Linker Makes and Reports Advanced DLL Facility Controls Identifier Severity 500-19999 Fatal Error 2000029999 Error 3000039999 Warning 4000049999 Informational Meaning The linker cannot do what was requested and it stops immediately. The linker cannot do what was requested and will eventually stop. The linker can continue but the results seem questionable. This does not indicate a problem. Messages are the same on all linker host platforms.
Advanced DLL Facility Controls Load-Time Operation -map tells the linker to report the virtual addresses and sizes of the segments and the sections, within each segment, of a loadfile being built. Further, the linker shows the library and file names of all liblisted libraries. -m is a synonym for -map. Load-Time Operation To load a program and its DLLs, the system is commanded simply to load the program.
Advanced DLL Facility Controls Controlling the Loader’s Search Path at Load Time In either case, the loader’s search path that was defined at link time is augmented as follows, where the paths identified at link-time were steps 2, 3, 6, and 7, as described in The Link-Time-Defined Search Path of the Loader on page 2-17. 1. The directories or subvolumes specified at load time by _RLD_FIRST_LIB_PATH. 2. The directories or subvolumes specified in -RLD_first_L options at link time 3.
Advanced DLL Facility Controls Changing Run-Time Options for C and C++ Programs You can prevent the loader’s search path for your loadfile from deviating from what you set up at link time, that is, restrict the loader’s search path to steps 2, 3, 6, and 7 above. You do this by having inserted the -limit_runtime_paths option in the linker’s command stream; see The Link-Time-Defined Search Path of the Loader on page 2-17.
Advanced DLL Facility Controls Changing Run-Time Options for C and C++ Programs DLL Programmer’s Guide for TNS/E Systems—527252-006 5-16
6 Example Code This section contains a set of examples to introduce you to some of the tools and capabilities for building dynamic linked libraries on a TNS/E system. Example One. This example creates a PIC program running with a DLL, using the TNS/E native compiler and linker. Example Two. This session demonstrates dynamic loading. We create and compile a main and a DLL, but don’t load the DLL. We invoke rld, the run-time loader, from inside the process by using a dlopen() call.
Example One Example Code Example One This example shows the use of a main program, mainstrc, and a library called mystrngc. Both will be compiled using ccomp, then linked using eld. mystrngc will be loaded as a DLL. Display the Source Code Here is the code for the main program, mainstrc #include nolist #include nolist #include
Example One Example Code char *pBegin; char *pEnd; char c; strcpy(r, s); pBegin = r; pEnd = r + strlen(r); while (--pEnd > pBegin ) { c = *pBegin; *pBegin++ = *pEnd; *pEnd = c; } return (0); } /* StrRev */ Compile the Program and Library The first step is to compile the programs using ccomp, the native mode TNS/E compiler, on the HP NonStop operating system to create the two object files, mainstro and mystro. We are using a fully-qualified filename to get to the TNS/E compiler, ccomp.
Example One Example Code Here’s the creation of the object file called mystro. run $data01.toolsy02.ccomp /in mystrngc /mystro;suppress TNS/E C - T0549H01 - 30AUG2004 (Oct 25 2004 14:47:23) (C)2004 Hewlett Packard Development Company, L.P. 0 remarks were issued during compilation. 0 warnings were issued during compilation. 0 errors were detected during compilation. Object file: mystro Compiler statistics phase CPU seconds elapsed time CCOMP file name \SPEEDY.$DATA01.TOOLSY02.CCOMP CCOMBE 0.
Example One Example Code The following command input creates the DLL: run $data01.toolsy02.eld mystro -o mystrdll -shared -export_all eld - TNS/E Native Mode Linker - T0608H01 - 26OCT04 Copyright 2004 Hewlett-Packard Company eld command line: \speedy.$data01.toolsy02.eld mystro -o mystrdll -shared -export_all **** INFORMATIONAL MESSAGE **** [1530]: Using 'ImpImp' file: \speedy.$data01.toolsy02.zimpimp. Output file: mystrdll (dll) Output file timestamp: Nov 8 13:59:43 2004 No errors reported.
Example One Example Code 60> run $data01.toolsy02.eld $data01.toolsy02.ccplmain mainstro -lib mystrdll& 60> & -lib zcredll -lib zcrtldll -o revstr -L $users.patrick -L $data01.toolsy02 -verbose eld - TNS/E Native Mode Linker - T0608H01 - 26OCT04 Copyright 2004 Hewlett-Packard Company eld command line: \speedy.$data01.toolsy02.eld $data01.toolsy02.ccplmain mainstro -lib mystrdll -lib zcredll -lib zcrtldll -o revstr -L $users.patrick -L $data01.
Example Two Example Code Example Two This example was created using TNS/R tools, thus uses ld instead of eld as the linker. The use of the dynamic loader rld is the same on either TNS/R or TNS/E. This session demonstrates dynamic loading. We create and compile a program and a DLL, but don’t load the DLL with the program. We invoke the loader from inside the process with a dlopen() call.
Example Two Example Code result = dlclose(dlopenHandle); dlopenHandle = 0; /* demonstrate the error routines */ dlopenHandle = dlopen("NotThere",RTLD_NOW); if (dlopenHandle == 0) { res.resCode = dlresultcode( ); printf("dlopen of a non-existent dll returns result %i\n" ,res.resCode); printf("\terror( %i,%i)\n" ,res.err[0], res.err[1]); printf( "%s\n", dlerror( ) ); return (1); } return 0; } /* of proc main */ The source code for helloc is as follows: #include
Example Two Example Code The compile for helloc is as follows: NMC /IN helloc/helloo;suppress, OPTIMIZE 0,SYMBOLS,ERRORS 5,EXTENSIONS,call_shared TNS/R Native Mode Risc C - T9577D46 - 30APR2003 (Mar 23 2003 19:42:26) (C)2000 Compaq (C)2003 Hewlett Packard Development Company, L.P. 0 remarks were issued during compilation. 0 warnings were issued during compilation. 0 errors were detected during compilation. Object file: helloo Compiler statistics phase CPU seconds elapsed time file name NMC \DLLQA.$SYSTEM.
Example Two Example Code Next, the main executable file is built. Note that the main program does not use -l to refer to hellodll at link time. ld maino -o mainexe -obey $SYSTEM.SYSTEM.libcobey -L $OSS.NSKAPAT4 $SYSTEM.SYSTEM.CCPPMAIN -l ZRLDSRL LD (T0429G09 - 30APR2003) (C)2003 Hewlett Packard Development Company, L.P. T0429's command line: maino -o mainexe -obey $SYSTEM.SYSTEM.libcobey -L $OSS.NSKAPAT4 $SYSTEM.SYSTEM.CCPPMAIN -l ZRLDSRL LD INFORMATIONAL MESSAGE **** [40056]: Entering OBEY file '$SYSTEM.
Example Two Example Code You can use the process name with LOADEDFILES, but can also refer to it by cpu, number which we do in this TACL example. status *,user,pri Process 3,301 Pri PFR %WT Userid 168 000 180,1 Program file $OSS.NSKAPAT4.MAINEXE Hometerm $ZTN10.#PTBSQW8 Comment: This is before the first dlopen(). $OSS NSKAPAT 8> loadedfiles 3,301 PROCESS NAME = UNNAMED PROCESS TYPE FILENAME PPROG \DLLQA.$OSS.NSKAPAT4.MAINEXE SRL \DLLQA.$SYSTEM.SYS00.ZCRESRL SRL \DLLQA.$SYSTEM.SYS00.ZSECSRL SRL \DLLQA.
Example Two Example Code SRL SRL SRL SRL Total No. \DLLQA.$SYSTEM.SYS00.ZCRTLSRL \DLLQA.$SYSTEM.SYS00.ZOSSKSRL \DLLQA.$SYSTEM.SYS00.ZOSSFSRL \DLLQA.$SYSTEM.SYS00.
A Linker Options List This section lists all the options supported by the TNS/E linker. For each one the complete syntax is shown, a brief statement of its function is given, and a hyperlinked reference is given to the main discussion of it elsewhere in this manual. If no hyperlink exists the option is either a synonym so look for the other option name, or the option is not covered in this manual and so you should consult the eld Manual for further details.
Linker Options List -change Change the parts of an existing object file corresponding to things that the -set option would set up. The and have the same possibilities as for the -set option shown below. See Changing the Attributes of an Existing Loadfile on page 5-9 . -check_registry Use the specified DLL registry to tell where the DLL being built must be placed in memory.
Linker Options List -export_not This is a synonym for -hidden_symbol. -first_L The specified directory or subvolume is one of the places where the linker will look for DLLs and archives before it looks for public DLLs. See Where The Linker Searches for Libraries and Archives on page 2-11. -FL This is a synonym for -obey. -grow_data_amount Leave the specified amount of slack space in virtual memory for the data of this DLL.
Linker Options List -instance_data { data1 | data2 | data2protected | data2hidden | data1constant } This tells the linker whether to create one or two data segments, and whether to require that the loadfile have no data that would need to go into the data variable segment if two segments were created. Note. The data2protected parameter is supported only on NonStop systems running J06.09 or earlier J-series RVUs and H06.20 or earlier H-series RVUs.
Linker Options List -make_import_lib Create a complete or incomplete import library with the specified filename, to represent the other DLL or DLLs whose filenames are found in the command stream. -map Produce a map showing how memory has been laid out. See Command Stream Requests for Linker Messages on page 5-12. -must_preset Consider it an error if presetting fails.
Linker Options List -no_stdfiles This is a synonym for -nostdfiles. -nostdlib Do not look in the standard places for DLLs and archives. See Where The Linker Searches for Libraries and Archives on page 2-11. -no_stdlib This is a synonym for -nostdlib. -noverbose This is a synonym for -no_verbose. -no_verbose Do not show warnings or informational messages unless they are requested by a linker option. See Message-Control Options on page 5-12. -o Use this as the name of the output object file.
Linker Options List -rld_first_L The string specified by should be a list of directories or subvolumes separated by colons. At runtime, the specified directories or subvolumes are places where rld will look for DLLs before it looks for public DLLs. SeeThe LinkTime-Defined Search Path of the Loader on page 2-17. -rld_L The string specified by should be a list of directories or subvolumes separated by colons.
Linker Options List Table A-1. Set Attributes (continued) Attribute Name Allowable Values Default incomplete on (note: only one allowable value, so it is therefore also required) If not specified, and an import library is being created, it is a complete import library. inspect on | off on libname If not specified, there may be no user library, or the name may be derived from what is specified for the -local_libname option.
Linker Options List -stdin Use the standard input file as an obey file. See Direct Use of the Linker on page 2-1. -strip Remove the DWARF symbol table from an existing loadfile or import library. -t Use the specified value as the starting address of the text segment of the loadfile being built. See Specifying the Preferred Location of a Loadfile in Virtual Memory on page 5-8.
Linker Options List -verbose Show all messages. See Message-Control Options on page 5-12. -warn Show all error and warning messages. See Message-Control Options on page 5-12. -warning_unresolved This is a synonym for -unres_symbols warn. -x Omit the DWARF symbol table when creating the output file. -y Provide information about how this symbol is mentioned in the ELF symbol tables of the linker’s input files. See Command Stream Requests for Linker Messages on page 5-12.
Glossary Archive file. This file contains copies of other files, called the "members" of the archive. An archive may be used for various purposes, one of which is to be an input for the linker. The linker uses archives as a source of linkfiles. Archives are not used at load time. Big endian. This term describes a method of storing data so that the most significant byte appears in a lower-numbered location in memory. As with TNS/R, TNS/E data structure is big endian.
Export. Glossary Export. To provide a symbol definition for use by other loadfiles. A loadfile offers for export a symbol definition for use by other loadfiles that need a data item or function having that symbolic name. Gateway. For every callable function there is a gateway; all calls to the function jump first to the gateway, which effects the transition to privileged state if the caller is not already privileged.
Glossary Indirect reference (of a loadfile). and run. It is useful in cross-linking. See Implicit library import library (imp-imp) and Zimpimp file. Indirect reference (of a loadfile). A library in a loadfile’s searchList that is not named in its libList. iniTerm Lists. Lists of initialization and termination functions used in the support of runtime dynamically-loaded libraries on the HP NonStop operating system. Instance. A particular case of a class of items, objects, or events.
Loadfile Glossary system. For PIC loadfiles and all TNS/E native programs, the loader called rld works with the operating system to load programs and libraries. Loadfile. This term describes the input to the runtime loader and default output of the linker. This object file may contain name references to symbols that exist in other loadfiles in the same process. Such references are typically resolved when the loadfiles are brought into memory by the runtime loader rld .
Program Glossary at link time. PIC is executable code that need not be modified to run at different virtual addresses. External reference addresses appear only in a data area that can be modified by the loader; they do not appear in PIC code. PIC code is even more position independent than one might imagine from the term; it can be simultaneously mapped to different addresses for different processes in the same CPU.
Sections and Segments Glossary searchList. A loadfile's searchList is unaffected by the import control of any other loadfile. Sections and Segments. The TNS/E object file is organized into contiguous items called sections. There is an array of ELF section headers that contains the type and name of each of these section items. A section is not required to be present if it would not contain any useful information for a given object file.
TLB. Glossary TLB. Translation Lookaside Buffer: a cache of page table entries, where each entry designates the physical memory page corresponding to a range of virtual addresses. Information within the entry can make the translation unique to the accessing process. Unless the appropriate TLB entry is present, the page cannot be accessed; typically the processor generates a fault to allow software to find and load the missing entry from a memory-management structure. TNS/E object file format.
Zreg file Glossary what was previously called the system library. See also Implicit library import library (imp-imp). Zreg file. This is the name of the public DLL registry file, which lists the names of all the public DLLs.
Index A added load set 3-3 ambiguity example 4-8, 4-9 warning 4-11 ambiguous symbols 4-5 archive 1-11, 2-7 repeated insertion 2-8 Archive file Glossary-1 argument, of a command-stream option 2-1 attributes, see loadfile attributes augmenting file names 2-4, 2-11, 5-2 augmenting library names 5-2 auxiliary linkfile 1-11 auxiliary system 1-7, 2-1 B Big endian Glossary-1 bind symbols 1-1 Bundle Glossary-1 C C and C++ I/O Files 5-15 C library, dlfcn.
E Index dynamically loaded DLL 1-8, 3-1 include file 3-2 dynamic-linked library, see DLL E EDIT Line Number Glossary-1 eld 1-6, 2-1 eld output 2-3 eld Specifics 2-5 ELF Glossary-1 entry point 5-4 error, dlclose returned values 3-7 error, dlopen mode parameter 3-5 returned values 3-5 unresolved symbols 3-3 error, dlsym returned values 3-6 error, dynamic library call analysis data 3-8 error, linker avoiding errors 2-22 consequence of an error 2-23 during -change processing 5-9 error codes 5-11 library unav
H Index H handle 3-2 invalidate 3-7 main program 3-5 open 3-5 highpin 5-7 highrequestors 5-7 Hybrid file Glossary-2 I implicit libraries 4-13 Implicit library Glossary-2 Implicit library import library (impimp) Glossary-2 Import Glossary-2 Import control Glossary-2 import control 1-11 default 1-12 Import library Glossary-2 import symbol 1-2 include
M Index linkfile 1-6 duplicate data items in 5-2, 5-3 duplicate procedure names in 5-3 linkfile inputs to a link 2-7 linking 1-6 to standard runtime libraries 2-9 load image, executable load image 1-5 load time 1-8 Loadable Library Glossary-4 Loader Glossary-3 loader 1-7 error, see error, loader load-time controls 5-13 making search path same as linker’s 5-14 resolving symbols 1-8 search path 2-17, 5-14 unresolved symbol 5-8 Loader Library Glossary-4 Loadfile Glossary-4 loadfile 1-1, 1-6 globalized 1-11,
P Index Option (continued) -dll 2-3 -dllname 2-3 -e 5-4 -export 5-5 -export_all 2-13, 5-5 -export_not 5-5 -first_L 2-11 -FL, see Option -obey -include_whole 2-7 -lib 2-10 -libname 2-12 -libvol 2-11 -limit_runtime_paths 2-18 -l, see Option -lib -L, see Option, -libvol -l.
S Index resolution 4-13 resolve symbol 1-1 resolved file name 2-4 Re-exported library Glossary-5 re-exported library 2-14 RLD, see loader runnamed 5-8 Running the Linker Through the Compiler 5-10 runtime attributes 5-6 libraries 1-10, 2-9 linker, see loader loading a DLL 3-2 opening a DLL 3-2 runtime-loaded DLL, see dynamically loaded DLL S saveabend 5-8 search path 2-11 linker 2-11 loader 2-17, 5-13 search range 4-5 search sequence 4-5 searching for augmented names 2-11, 5-2 SearchList Glossary-5 search
V Index V VHPT Glossary-7 VPROC Glossary-7 W warning of ambiguity, see ambiguity warning where the linker searches for files See linker, search path where to insert library names 2-9 X xport bit in external symbol table 2-13 Z Zimpimp file Glossary-7 Zreg file 1-10, Glossary-8 Special Characters DLL Programmer’s Guide for TNS/E Systems—527252-006 Index-7
Special Characters Index DLL Programmer’s Guide for TNS/E Systems—527252-006 Index-8
