RLD Manual Abstract This document describes the runtime linker (also called the runtime loader) that provides support for Dynamic-Link Libraries (DLLs) and their client programs, both of which use Position Independent Code (PIC). The description of all functionality is the same on TNS/R and TNS/E unless specifically noted as being for one or the other. Product Version N/A Supported Release Version Updates (RVUs) This manual supports G06.20, H06.03, and J06.
Document History Part Number Product Version 528857-002 528857-003 528857-004 528857-005 528857-006 N/A N/A N/A N/A N/A Published February 2005 July 2005 April 2011 February 2012 October 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.
RLD Manual Glossary Index Legal Notices What’s New in This Manual Manual Information New and Changed Information About This Manual Related Information Notation Conventions RLD Overview Installation for TNS/R Installation for TNS/E How the HP NonStop Operating System works with rld The Library Functions How rld Operates IniTerm Functions Loader Path Specifications Link-time Path Specifications Load-time Path Specifications Complete Loader Path List Unresolved Symbols Security Considerations Loader Diagno
Contents Glossary Glossary Index RLD Manual—528857-006 ii
What’s New in This Manual Manual Information RLD Manual Abstract This document describes the runtime linker (also called the runtime loader) that provides support for Dynamic-Link Libraries (DLLs) and their client programs, both of which use Position Independent Code (PIC). The description of all functionality is the same on TNS/R and TNS/E unless specifically noted as being for one or the other. Product Version N/A Supported Release Version Updates (RVUs) This manual supports G06.20, H06.03, and J06.
What’s New in This Manual Changes to the 527252-004 Manual Updated introduction for the chapter Using the rld Loader Library on page 2-1. Added a new term Neutral loadfile on page -4 to the glossary. Changes to the 527252-004 Manual Updated the section IniTerm Functions on page 1-5. Updated the section Load-time Path Specifications with examples on page 1-7. Added a new verbosity level to the section Loader Diagnostic Message Verbosity Level on page 1-10.
About This Manual This document is intended for use by programmers who will use rld to dynamically load DLLs on either G, H, or J-series software. It is assumed that you have some previous knowledge of using the native linker in your chosen environment. Section 1, RLD Overview contains an overview of the rld facility. Section 2, Using the rld Loader Library contains detailed descriptions of the C programming functions.
About This Manual General Syntax Notation UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH lowercase italic letters. Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name computer type. Computer type letters within text indicate C and Open System Services (OSS) keywords and reserved words.
About This Manual General Syntax Notation … Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times. For example: M address [ , new-value ]… [ - ] {0|1|2|3|4|5|6|7|8|9}… An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times. For example: "s-char…" Punctuation.
About This Manual !i:i. Notation for Messages In procedure calls, the !i:i notation follows an input string parameter that has a corresponding parameter specifying the length of the string in bytes. For example: error := FILENAME_COMPARE_ ( filename1:length , filename2:length ) ; !i:i !i:i !o:i. In procedure calls, the !o:i notation follows an output buffer parameter that has a corresponding input parameter specifying the maximum length of the output buffer in bytes.
About This Manual Change Bar Notation 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.
About This Manual Change Bar Notation RLD Manual—528857-006 x
1 RLD Overview This document describes the runtime linker (also called the runtime loader) that provides support for Dynamic-Link Libraries (DLLs) and their client programs, both of which use Position Independent Code (PIC). The description of all functionality is the same on TNS/R and TNS/E unless specifically noted as being for one or the other. Support for building a DLL from compiler generated object files, is provided by the linkers; ld on TNS/R and eld on TNS/E.
RLD Overview The Library Functions their libraries. The rld functionality is provided through a function called RLD_Main in the loader library that the operating system invokes when a PIC loadfile is specified for process creation. The loader library is special in that it has an entry point address in its ELF header, unlike ordinary SRLs and DLLs.
RLD Overview How rld Operates rld uses a procedure call to establish a session between the operating system and itself. The function returns the name of the main program and keys representing the rld loadfile itself, the public library set, user library and the main program. 2. rld constructs the loadList rld adds the main program to the loadList followed by the user library, if any. Then starting with the libList of the main program, it finds and opens the required libraries.
RLD Overview How rld Operates If that “unresolved” symbol is needed and cannot be found, rld reports an error to the operating system and aborts the load. If the operating system informed rld that the rebind is shared, rld reports back the final LIC to the operating system (which can cache or update the bindings in the loadfile). rld rebinds the special C++ globalized symbols, if any, using the globalized search rules. The search differs between TNS/R and TNS/E.
RLD Overview IniTerm Functions The dlopen() function loads the specified DLL and all the libraries on its loadList. This function shares the rld phases 2 to 5 previously described, with variations in phase 2 and 5: In phase 2, the function argument specifying the library to be dynamically loaded provides the starting point for creating the loadList, rather than the program's libList.
RLD Overview Loader Path Specifications C++ generates local functions to invoke static constructors and destructors for global variables that are instances of classes.The linker (eld) builds two iniTerm lists and places pointers (ctors and dtors addresses) to them in the tandeminfo segment of the object file. The loader (rld) explicitly relocates the function pointer addresses within the lists when the loadfile is rebased.
RLD Overview Load-time Path Specifications Default locations for a 64-bit process: On OSS: /lib64, /usr/lib64, /usr/local/lib64, /lib, /usr/lib, /usr/local/lib, /G/SYSTEM/YDLL, /G/SYSTEM/ZDLL, in that order The linker, can place either or both of two path lists in the loadfile, using the following options: -RLD_L [:]… This option specifies one or more places for the runtime loader to look for libraries.
RLD Overview Complete Loader Path List add define=_RLD_FIRST_LIB_PATH, class search, subvol0 $data05.
RLD Overview Security Considerations Run the program despite references to unresolved procedures, without a warning. When an error occurs, rld does not continue to run, dlopen() will return a handle with a value of zero and a summary message can be retrieved by a call to dlerror(), or the error code can be retrieved by a call to dlresultcode().
RLD Overview Loader Diagnostic Message Verbosity Level The first rule ensures that privileged code is authorized. A file can be licensed by only user SUPER.SUPER (User-id 255,255); licensed imputes trust that the code will not abuse its privilege. The second rule ensures that trusted code does not invoke untrusted code, so it cannot be "spoofed." The third rule ensures that untrusted, unprivileged code cannot damage data upon which the privileged code depends.
RLD Overview Loader Diagnostic Message Verbosity Level RLD Manual—528857-006 1-11
RLD Overview Loader Diagnostic Message Verbosity Level RLD Manual—528857-006 1-12
2 Using the rld Loader Library You can load, use, and manage DLLs dynamically by using these run-time linking functions from the rld loader library: dlopen() opens and loads a DLL dynamically from within your application. dlsym() accesses the symbols of a dynamically-loaded DLL. dlclose() closes a DLL loaded previously by dlopen(). dlresultcode() returns the error code for the most recent call to dlopen(), dlclose(), or dlsym().
Using the rld Loader Library dlopen() dlopen() Summary The dlopen() function opens a DLL loadfile from a running process. Syntax for C/C++ Programmers #include dlHandle dlopen ( const char *object_pathname, int mode ); Parameters object_pathname points to the null-terminated file name of the DLL to be opened.
Using the rld Loader Library dlopen() loaded. Note that any handle returned by dlopen()counts as a usage of the target library and until it is closed, the library is not unloaded. RTLD_VERBOSE(n) specifies the amount and type of debugging information to provide on the home terminal or standard error file when an error occurs.
Using the rld Loader Library dlopen() Return Values Upon successful completion, the dlopen() function returns a library handle valid for use with other DLL functions. This handle is an arbitrary token, not an address. It cannot be assigned to a pointer and dereferenced.
Using the rld Loader Library dlopen() The dlopen() function does not set the errno variable. For error information, call the dlerror() or dlresultcode() function. Unresolved Symbols Unresolved symbols can cause dlopen() to generate warnings or errors, depending on the user-specified option for treating unresolved symbols. If the option saved in the object file specifies that unresolved symbols generate errors, dlopen() returns 0 (zero) without loading any DLLs.
Using the rld Loader Library dlsym() dlsym() Summary The dlsym function obtains the address of an external symbol in a DLL. Syntax for C/C++ Programmers #include void *dlsym ( dlHandle dlopen_handle, const char *symbol_name ); Parameters dlopen_handle specifies a currently valid library handle previously returned by a call to the dlopen function. The handle must have not been invalidated using dlclose.
Using the rld Loader Library dlsym() Considerations The dlsym() function allows a process to obtain the address of an external symbol defined within any loadfile currently loaded in the process. A dlopen_handle returned by a call of the form dlopen(0, mode) causes the symbol search to occur on the cumulative loadList (that is, on the main program and all the explicit DLLs currently loaded in the process, in the order they were loaded initially by rld and subsequently by calls to dlopen).
Using the rld Loader Library dlclose() dlclose() Summary The dlclose() function invalidates the library handle designated by the dlopen_handle value. It unloads any DLLs that are no longer required. Syntax for C/C++ Programmers #include int dlclose (dlHandle dlopen_handle ); Parameters dlopen_handle specifies a currently valid library handle previously returned by a call to the dlopen() function. Return Values Upon successful invalidation of the library handle, dlclose() returns 0 (zero).
Using the rld Loader Library dlclose() Examples In the following program, suppose that library A requires library C (because C is specified on the libList of A), and that library B also requires library C: hA = dlopen("A", ...); // loads A and C; links A to C. hB = dlopen("B", ...
Using the rld Loader Library dlresultcode() dlresultcode() Summary The dlresultcode() function returns the error code for the most recent call to dlopen(), dlclose(), or dlsym(). Syntax for C/C++ Programmers #include extern int dlresultcode(void); Parameters None. Return Values Upon successful completion of the call, dlresultcode() returns either a 0 (zero), if no previous error has occurred, or returns the nonzero value for the error detected.
Using the rld Loader Library dlresultcode() Considerations The dlresultcode() function retrieves the last error code generated by a call to any of the functions dlopen(), dlclose(),or dlsym(). This function can be used instead of the dlerror() function when a number is needed instead of a text string error message. Immediately after the call to the function for which you want to check the returned error value, call the dlresultcode() function.
Using the rld Loader Library dlerror() dlerror() Summary The dlerror() function returns an explanation of a previous DLL error. Syntax for C/C++ Programmers #include char *dlerror(void); Parameters None. Return Values Upon successful completion, following a previous call to a DLL function that failed, dlerror() returns a null-terminated character string. Otherwise, dlerror() returns a null pointer. The returned string has these: Does not have a trailing new-line character.
Using the rld Loader Library dlerror() The dlerror function returns a null pointer if you call it in either of these situations: Before you call any other DLL function Immediately after you call dlerror() itself (regardless of the value returned by the previous call) You can obtain the numeric form of the error by calling the dlresultcode() function. You can call dlresultcode() immediately before or after calling dlerror(). Neither function affects the information returned by the other.
Using the rld Loader Library dlerror() RLD Manual—528857-006 2-14
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.
Glossary Export. 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.
Glossary Loadfile 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 .
Glossary Program at link time. 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.
Glossary Sections and Segments 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.
Glossary TLB. 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.
Glossary Zreg file set of implicit DLL's, which collectively correspond to what was previously called the system library. See also Implicit library import library (imp-imp). Zreg file. This is the internal name of the public DLL registry file, which lists the names of all the public DLL's.
Index A H Archive file Glossary-1 How NSK works with rld 1-1 Hybrid file Glossary-2 B I Big endian Glossary-1 Bundle Glossary-1 C Client (of a loadable library) Glossary-1 Code file Glossary-1 D Default Glossary-1 Direct reference (of a loadfile) Glossary-1 dlclose 2-8 DLL file Glossary-1 dlresultcode 2-10 dlsym 2-6 Dynamic loading Glossary-1 E EDIT Line Number Glossary-1 ELF Glossary-1 Explicit library Glossary-1 Export Glossary-2 F FastLoad 1-2 FastLoadable loadfile 1-3 G Gateway Glossary-2 Gbl
Index P U MCB. The Master Control Block.
