Ingres CL DL
From Ingres Community Wiki
|
Ingres Compatability Library |
Contents |
Compatibility Library Specification - DL
Abstract
This is the specification of the DL facility provided by the compatibility library for the dynamic loading mechanism.
Revision 1.5 22-May-2008.
Document History
- Revision 1.5, last revised 22-May-2008
- Formatted for Ingres Community Wiki.
- Added DLload.
- Revision 1.4, 10-Feb-1998
- Add extra parameters for DLcreate_loc.
- Added entry for DLconstructloc.
- Revision 1.3 24-Mar-1997
- Updated to HTML format.
- Added entries for DLcreate_loc, DLprepare_loc and DLdelete_loc.
- Revision 1.2 10-Oct-1996
- Added more detailed description of DL modules on different platforms.
- Removed restriction of one module per process.
- Revision 1.1 30-Jul-94
- Corrected typo in version (was 0.2 places it should have been 1.0).
- Revision 1.0, last modified 20-Sep-91
Specification
Introduction
Library routines to interface to dynamic linking mechanism.
Library
CL
Intended Uses
The routines in the DL module manage the loading and unloading of shared library images into a calling application.
Functions of the DL module are used in 3GL routines called from W4GL code. Others clients of DL include the ODBC CLI and applications that use dynamically-loaded security mechanisms, such as Kerberos.
All of these routines return an Ingres status code. No exceptions are reported.
These routines can be implemented in a system independent fashion.
There are two steps to loading a module into a running program in a W4GL environment:
- When building a 3GL image to be executed from a W4GL program, the module must be prepared. This means:
- Compiling and linking the 3GL modules.
- Doing as much of the relocation and symbol table resolution as possible.
- Saving the resultant file in a known location.
- Binding that module to the address space of the running program. DL breaks this into two steps:
- DLprepare, DLprepare_loc, or DLload loads the image into the calling program and makes the module available for binding.
- DLbind maps the image to a specified function name.
The first step (creating the module) is run by a developer as part of creating a W4GL application. The second step (loading and binding) will be run by the end user every time the application is run. Outside of the W4GL environment, only the second step is required.
Assumptions
The operating system must support a dynamic linking mechanism, or at least the ability to add executable code to the address space of a running program.
Definitions
| Executable File | An executable file is a binary image that can be executed as the result of a compile and link operation. |
| Object File | Often called a "shared object file" , this is the output of the compiler. A platform may require that the function entry points of the object file are "position-independent" . |
| DL module | The output of DLcreate. A DL module is a shared library image file. |
| The "DL module" name is a string of lower case alphanumeric characters, null-terminated, beginning with a letter. | |
| W4GL is structured so that the DL modules reside in the directory referred to by the IIDLDIR logical name. If this value is not set, it defaults to $II_SYSTEM/ingres/files/dynamic. These are the requirements of DLprepare. Ingres normally does not have this requirement; the DL modules typically reside in the Ingres library directory, and uses DLos_prepare or to load tye DL module according to the specified path, usually the library directory of Ingres. If DLload is used, the Ingres library directory is always used. | |
| DLload uses the file name as an input argument and thus does not require any special formatting of the DL module name. | |
| Load | The act of binding a file into the virtual address space of a particular process and resolving symbol references. |
| Link-edit | The act of taking input object/executable files in W4GL and resolving symbols to create a loadable file image. |
Naming Convention for DL modules:
DLprepare and DLos_prepare excpect the DL modules to be formatted as follows:
| All versions of Unix and linux except HP/UX | libmodule.so.2.0 |
| HP/UX | libmodule.sl |
| VMS | libmodule.exe |
| Windows | libmodule.dll |
Header File <dl.h>
The header file <dl.h> must be included before using any of the functions provided. The <dl.h> file is located at gl!hdr!hdr.
The <dl.h> header file includes a <dlcl.h> file. There are three versions of <dlcl.h>, one each for Windows, Unix/Linux, and VMS.
Error codes
The following status values are defined, and may be returned by DL functions as described in the individual function specifications.
| DL_FUNC_NOT_FOUND | A function requested is not part of this DL module associated with the handle. This may happen if the function wasn't on the list given to DLcreate or DLprepare. |
| DL_MOD_NOT_FOUND | The requested module couldn't be found. |
| DL_NOT_IMPLEMENTED | The mechanism isn't implemented on this platform. |
| DL_MOD_NOT_READABLE | The requested module exists, but cannot be read. |
| DL_WRONG_VERSION_MOD | If versioning was requested, but the module didn't contain a version or the versions didn't match. |
| DL_OSLOAD_FAIL | The module could not be loaded for some other reason. The OS error information will be returned in err. |
Executable Interface
The following functions are provided:
DLbind
Bind a function and return the address of its function entry point.
DLbind utilizes a handle returned by DLprepare, DLload, or DLosprepare, validates the specified function from the loaded image, and returns the address of the function if successful.
Only functions present on the lists passed to DLcreate, DLprepare, DLprepare_loc, or DLoad should be bound. Some platforms allow DLbind to succeed on a given function, even though the function was not explicitly referenced in the symbol list passed to a DL loading function; this is not guaranteed to succeed on all platforms.
Definition:
STATUS DLbind(handle, *functionName, functionAddr, osError) PTR handle; char * functionName; PTR * functionAddr; CL_ERR_DESC * osError;
Inputs:
| handle | The handle returned by a successful call to DLprepare. The handle is not invalidated by a call to DLunload. |
| functionName | A null-terminated string representing the function name. |
Outputs:
| functionAddr | Upon successful return, this is set to the address of the function whose name was given in functionAddr. |
| osError | Pointer to variable used to return system-specific errors. |
Returns:
| OK | The function was successfully bound. |
| DL_NOT_IMPLEMENTED | The DL function is not implemented on this platform. |
| DL_FUNC_NOT_FOUND | The function requested is not part of this DL module implied in the handle. This could be because the function wasn't on the list given to DLcreate or DLprepare , or because the function is simply missing. |
| Other: | System specific error status. |
Side effects:
On some platforms, the binding of an object to the address space may occur when DLprepare is called; on others, when DLbind is called.
DLcreate
Create module for DLprepare/DLbind dynamic loading
Create a module which can be passed to DLprepare . The user provides a set of object-file names, library names, and a system-specific string. The string might contain the name of an executable against which to resolve symbols, or a system-specific shared object, or the like.
DLcreate might link-edit all of the object files given, resolving first against the symbol table of the executable file and then looking to the libraries for any unresolved symbols, or it might leave a permanent identification of the parts for later use by DLprepare and DLbind.
The list of libraries contains system-specific library designations, e.g. "-lm" and "SYS$LIBRARY:" . The list of libraries may be empty, and the name of the executable file may be given as NULL, which means "don't resolve against any executable file's symbol table." If no objects or libraries are supplied, nothing will be in the output module.
If the user provides a version string, it must be encoded into the output module for use by DLprepare .
The user provides a list of function names which will be made available to DLprepare for symbol table lookups. The list may be empty, in which case no functions are guaranteed to be in the output module. DLcreate must ensure that any functions in the list will be seen by a subsequent DLprepare and DLbind. The places the error checking burden on the program creating the module rather than on those attempting to load it later.
The operation of DLcreate is undefined if there are conflicts between the symbols defined by the exename and any of the input libraries. DLcreate might return an error, or it might create a module selecting one of the definitions at random.
Notes:
DLcreate is not implemented on the following platforms. Instead, the DL modules are created as a result of linker commands similar to the examples that follow:
| Operating System | Command | Output File |
| SunOS, Solaris | ld -G -o libmod.so.2.0 object.o | libmod.so.2.0 |
| Windows NT | link /DLL /OUT:mod.DLL /DEF:mod.DEF object.OBJ | mod.DLL |
| HP-UX | ld -b -o libmod.sl object.o | libmod.sl |
In these examples, "mod" is the DL module name as passed to DLprepare().
Definition:
STATUS DLcreate(exename, vers, dlmodname, char *in_objs, in_libs, exp_fcns, err) char * exename; char * vers; char * dlmodname; char * in_objs[]; char * in_libs[]; char * exp_fcns[]; CL_ERR_DESC * err;
Inputs:
| exename | If non-NULL (and *exename != EOS), a C string identifying the executable the output module will be used with, in a way that will allow symbol resolution if that is required. |
| vers | If non-NULL (and *vers != EOS), a pointer to a version string to be embedded in output module. |
| dlmodname | A pointer to a C string containing the name of a DL module to create, using the format described under Definitions . |
| in_objs | An array of C strings, with NULL entry as its last element, containing system-specific specifications for names of input object files. This list can specify zero libraries (in_objs[0] = NULL). |
| in_libs | An array of C strings, with NULL entry as its last element, containing system-specific specifications for names of input libraries. This list can specify zero libraries (in_libs[0] = NULL). |
| exp_fcns | An array of null-terminated strings, with NULL entry as the last element, containing the function names that can be found using DLprepare, DLprepare_loc, DLload, and DLbind. Note: On platforms that support operating-system calls to look up function entry points by name, this array is ignored, and can be replaced with NULL. This includes Solaris and Microsoft Windows. |
Outputs:
| err | Pointer to variable used to return system-specific errors. |
Returns:
| OK | The DL module has been successfully created. |
| DL_NOT_IMPLEMENTED | if the DL mechanism isn't implemented on this platform. |
| other | system specific error status. |
Side effects:
None.
DLcreate_loc
Create module in a specific location. DLcreate_loc is similar to DLcreate, but allows specification of a location other than the default to receive the created module.
Definition:
STATUS
DLcreate_loc(exename, vers, dlmodname, in_objs, in_libs, exp_fcns, loc,
parms, errloc, append, miscparms, err)
char * exename;
char * vers;
char *dlmodname;
char * in_objs[];
char * in_libs[];
char *exp_fcns[];
LOCATION * loc;
char * parms;
LOCATION * errloc;
bool append;
char * miscparms;
CL_ERR_DESC * err;
Inputs:
| exename | If non-NULL (and *exename != EOS), a C string identifying the executable the output module will be used with, in a way that will allow symbol resolution if that is required. |
| vers | If non-NULL (and *vers != EOS), a pointer to a version string to be embedded in output module. |
| dlmodname | A pointer to a C string containing the name of a DL module to create, using the format described under Definitions. |
| in_objs | An array of C strings, with NULL entry as its last element, containing system-specific specifications for names of input object files. This list can specify zero libraries (in_objs[0] = NULL). |
| in_libs | An array of C strings, with NULL entry as its last element, containing system-specific specifications for names of input libraries. This list can specify zero libraries (in_libs[0] = NULL). |
| exp_fcns | An array of C strings, with NULL entry as its last element, containing the function names that can be found using DLprepare and/or DLbind.
Note: On platforms that support operating-system calls to look up function entry points by name, this array is ignored, and can be replaced with NULL. This includes Solaris and Microsoft Windows NT. |
| loc | Pointer to a LOCATION structure that contains the directory where the module is to be created. |
| parms | Additional parameters passed on the command line. |
| errloc | Pointer to a LOCATION structure that contains the filename of a file that will receive any output from the command. May be NULL. |
| append | TRUE to append output to errloc, otherwise will overwrite errloc. |
| miscparms | A pointer to a string of comma-delimited parameters that can give hints to the linker. Currently the only parameter supported is "C++", which instructs the linker to include the C++ standard library. |
Outputs:
| err | Pointer to variable used to return system-specific errors. |
Returns:
| OK | The DL module has been successfully created. |
| DL_NOT_IMPLEMENTED | The DL mechanism isn't implemented on this platform. |
| other | System-specific error status. |
Side effects:
None.
DLdelete
Delete the persistent version of a DL module. Remove a DL module that has been created by DLcreate.
Description:
STATUS DLdelete(dlmodname, err) char * dlmodname; CL_ERR_DESC *err;
Inputs:
| dlmodname | The name of a DL module, using the format described under Definitions. |
Outputs:
| err | Pointer to variable used to return system-specific errors. |
Returns:
| OK | The module has been successfully removed, or wasn't there to begin with; a module of this name no longer exists. |
| DL_NOT_IMPLEMENTED | Returned if requested DL mechanism isn't implemented on this platform. |
| other | System-specific error status. |
Side effects:
None.
DLdelete_loc
Delete the persistent version of a DL module at a specific location. Remove a DL module that has been created by DLcreate where the module resides in a specific location.
Description:
STATUS DLdelete_loc(dlmodname, loc, err) char * dlmodname; LOCATION * loc; CL_ERR_DESC * err;
Inputs:
| dlmodname | The name of a DL module, using the format described under Definitions. |
| loc | Pointer to a LOCATION where the module resides. |
Outputs:
| err | Pointer to variable used to return system-specific errors. |
Returns:
| OK | The module has been successfully removed, or wasn't there to begin with; a module of this name no longer exists. |
| DL_NOT_IMPLEMENTED | Returned if requested DL mechanism isn't implemented on this platform. |
| other | System-specific error status. |
Side effects:
None.
DLload
DLload loads a named module from a specific location. The full name of the DL module is provided, and is not required to conform to the naming conventions required by DLprepare and DLprepare_loc.
Description:
STATUS DLload(ploc, dlmodname, syms, handle, errp) LOCATION * ploc; char * dlmodname; char * syms[]; PTR * handle; CL_ERR_DESC * errp;
Inputs:
| ploc | Pointer to a LOCATION structure that contains the directory where the module exists. |
| dlmodname | The full file name of a DL module, without qualifying paths or directory references. |
| syms | An array of null-terminated strings with a NULL pointer as the last element in the array. Each element in the array corresponds to an exported function in the DL module. |
Outputs:
| handle | A generic pointer used for management of DL support routines. |
| errp | Pointer to variable used to return system-specific errors. |
Returns:
| OK | The DL module was successfully located and loaded. |
| DL_MOD_NOT_FOUND | If the module couldn't be found. |
| DL_MOD_NOT_READABLE | The requested module exists, but cannot be read. |
| DL_NOT_IMPLEMENTED | The DL function is not implemented on this platform. |
| DL_WRONG_VERSION_MOD | Versioning was requested, but the module didn't contain a version or the versions didn't match. |
| DL_OSLOAD_FAIL | The module could not be loaded for some other reason. The OS error information will be returned in err. |
Side effects:
DLload modifies the address space of the invoking process. Memory associated with the DL handle may be allocated.
DLnameavail
DLnameavail checks that the object name can be used to create a DL module using DLcreate. Although it mainly checks that the name is unused by any existing DL module, it may return more information in the error returns.
Description:
STATUS DLnameavail(dlmodname, err) char * dlmodname; CL_ERR_DESC * err;
Inputs:
| dlmodname | The name of a DL module, using the format described under Definitions. |
Outputs:
| err | Points to variable used to return system-specific errors. |
Returns:
| OK | The name is available for use, that is, it's not currently in use by another DL module. |
| DL_NOT_IMPLEMENTED | The DL function is not implemented on this platform. |
| DL_MODULE_PRESENT | A DL module exists by that name already. |
| other | System-specific error status. |
DLprepare
DLprepare allows the given module to be bound to the address space of the invoking process, making the assumption that the module has been prepared by DLcreate or a process that imitates it. The module may or may not actually be bound at this time. Items will be bound when calls to DLbind succeed.
Although no performance requirements are given in this specification, DLprepare must be fast enough that a user-level program can bring user-provided code into its address space quickly.
The term "load" can mean as little as "makes a system call to instruct the OS to bind the module to the address space" or as much as "allocate memory and copy the entire contents of the module into the address space of the current process, relocating as necessary."
An error might be returned for any of the following reasons:
Insufficient address space; Insufficient file descriptors, if used in implementation; A necessary file was the wrong "file type" or lacked the requisite permissions. If a version string is given and is non-NULL, it's assumed that there is an internal version string stored in the loaded module to which it should be compared: they should be identical.
If that string hasn't been stored in the module, or if the two strings don't exactly match, an error is returned and the module isn't loaded.
A list of functions is given, which give information to DLprepare telling it which functions will potentially be resolved later, in case it needs to save information about those functions. Functions not handed in to DLprepare may not be visible at the time a DLbind is attempted.
Description:
STATUS DLprepare(vers, dlmodname, syms, handle, err) char * vers; char * dlmodname; char * syms; PTR handle; CL_ERR_DESC * err)
Inputs:
| vers | If non-NULL (and *vers != EOS), a pointer to a version string to be checked against one embedded in the loaded module. |
| dlmodname | The name of a DL module, using the format described under Definitions . This is used to construct the name of the DL module that's loaded into the address space, and must be the same string as the one passed to DLcreate to create the DL module. |
| syms | An array of null-terminated strings with a NULL pointer as the last element in the array. The strings represent the names of functions to be loaded into the calling image. The specified functions are not callable until DLbind is invoked. |
Outputs:
| handle | A generic pointer used for management of DL support routines. |
| err | Pointer to variable used to return system-specific errors. |
Returns:
| OK | The DL module was successfully located and loaded. |
| DL_MOD_NOT_FOUND | If the module couldn't be found. |
| DL_MOD_NOT_READABLE | The requested module exists, but cannot be read. |
| DL_NOT_IMPLEMENTED | If the DL mechanism isn't implemented on this platform. |
| DL_WRONG_VERSION_MOD | If versioning was requested, but the module didn't contain a version or the versions didn't match. |
| DL_OSLOAD_FAIL | The module could not be loaded for some other reason. The OS error information will be returned in err. |
Side effects:
DLPrepare modifies the address space of the invoking process. Memory may be allocated.
DLprepare_loc
DLprepare_loc loads a module from a specific location. DLprepare_loc is similar to DLprepare, but allows the module to be loaded from a specified location instead of the default.
Description:
STATUS DLprepare_loc(vers, dlmodname, syms, loc, flags, handle, err ) char * vers; char * dlmodname; char * syms; LOCATION * loc; i4 flags; PTR handle; CL_ERR_DESC * err;
Inputs:
| vers | If non-NULL (and *vers != EOS), a pointer to a version string to be checked against one embedded in the loaded module. |
| dlmodname | The name of a DL module, using the format described under Definitions. This is used to construct the name of the DL module that's loaded into the address space, and must be the same string as the one passed to DLcreate to create the DL module. |
| syms | An array of null-terminated strings with a NULL pointer as the last element in the array. Each element in the array corresponds to an exported function in the DL module. |
| loc | Pointer to a LOCATION structure that contains the directory where the module exists. |
Outputs:
| handle | A generic pointer used for management of DL support routines. |
| err | Pointer to variable used to return system-specific errors. |
| flags | Hints as to how symbol relocation should be handled at load time. These are recommendations only; the system may override. |
Value for the 'flags' argument:
| DL_RELOC_DEFAULT | Use system default |
| DL_RELOC_IMMEDIATE | Try to resolve all relocations immediately. |
| DL_RELOC_DEFERRED | Defer resolving relocations until later, usually when entry points are referenced. |
Returns:
| OK | The DL module was successfully located and loaded. |
| DL_MOD_NOT_FOUND | The DL module could not be found. |
| DL_MOD_NOT_READABLE | The requested module exists, but cannot be read. |
| DL_NOT_IMPLEMENTED | The DL function is not implemented on this platform. |
| DL_WRONG_VERSION_MOD | Versioning was requested, but the module didn't contain a version or the versions didn't match. |
| DL_OSLOAD_FAIL | The module could not be loaded for some other reason. The OS error information will be returned in err. |
Side effects:
DLprepare_loc modifies the address space of the invoking process. Memory associated with the DL handle may be allocated.
DLunload
DLunload releases the image from the calling program. DLunload destroys any bond between address space and dynamically loaded module. After DLunload returns successfully, the DL handle is no longer valid for use by DLbind.
Description:
STATUS DLunload(handle, err) PTR handle; CL_ERR_DESC * err;
Inputs:
| handle | A handle previously returned from DLprepare. DLprepare_loc or DLload. |
Outputs:
| err | Pointer to variable used to return system-specific errors. |
Returns:
| OK | The DL module has been successfully unloaded. |
| DL_NOT_IMPLEMENTED | The DL function is not implemented on this platform. |
| other | System-specific error status. |
Side effects:
Attempts to re-load the DL module may fail. Allocated memory may not be freed.
|
Ingres Compatability Library |
