sl@0: /** @file ../include/dlfcn.h sl@0: @internalComponent sl@0: */ sl@0: sl@0: /** @fn dlopen(const char *filename, int flag) sl@0: @param filename sl@0: @param flag sl@0: Note: This description also covers the following functions - sl@0: dlsym() dlerror() dlclose() sl@0: sl@0: @code sl@0: RTLD_LAZY In the current implementation this flag causes the external function names to be resolved sl@0: prior to returning from dlopen. sl@0: RTLD_NOW In the current implementation this flag causes the external function names to be resolved sl@0: prior to returning from dlopen. sl@0: sl@0: @endcode sl@0: @code sl@0: RTLD_GLOBAL Symbols exported from this shared library object will not be available sl@0: for the processing of relocation addresses of any other shared library object. sl@0: RTLD_LOCAL Symbols exported from this shared library object will not be available sl@0: for the processing of relocation of addresses in any other shared library object. sl@0: sl@0: @endcode sl@0: These functions provide interfaces to the services of the Symbian Loader sl@0: Server. Operations are provided to load dynamic link libraries (DLLs) into the sl@0: current process's address space, to obtain the address bindings of symbols sl@0: exported by the DLLs, and to remove the DLLs from the process's address space sl@0: when they are no longer required. sl@0: sl@0: The dlopen function loads the DLL specified in the filename argument and returns a descriptor if successful. The descriptor sl@0: returned can be used for later references to the DLL within the calls to dlsym and dlclose. The user side code should not attempt to modify or interpret sl@0: the value of the descriptor returned by dlopen. sl@0: sl@0: If the DLL specified by the filename argument is not in the address space prior to the call to dlopen, it is loaded into the address space. When the DLL is first sl@0: loaded into the address space constructors of the DLL's global objects sl@0: are invoked. If the DLL specified by the filename argument has already been placed in the process's address sl@0: space in a previous call to dlopen, invoking dlopen on the same DLL does not add it a second time, instead the sl@0: reference count of dlopen operations on that DLL is incremented. Invoking dlclose on the DLL handle decrements the reference count associated sl@0: with the DLL. When this reference count reaches zero, the DLL is unloaded from sl@0: the process address space. dlopen returns NULL if path argument is NULL. sl@0: sl@0: The mode parameter determines the type of operation performed by dlopen with respect to the symbol address relocations and the visibility sl@0: of the symbols to other shared libraries loaded by the process. The mode argument has the same effect regardless of its value: It is to sl@0: resolve all the external function references immediately within dlopen. This is because the external function references are bound sl@0: immediately by dlopen. For all practical purposes, therefore, the mode parameter's value is assumed to be RTLD_NOW ORed with RTLD_LOCAL. sl@0: Once a DLL is loaded into the address space, all the symbols exported by it sl@0: can only be accessed by specifying the handle associated with the DLL. The behaviour sl@0: is outlined below. sl@0: sl@0: mode must contain one of the following values, possibly ORed with additional sl@0: flags described below: RTLD_LAZY In the current implementation this flag causes the external function names to be resolved sl@0: prior to returning from dlopen. RTLD_NOW In the current implementation this flag causes the external function names to be resolved sl@0: prior to returning from dlopen. sl@0: sl@0: One of the following flags may be ORed into the mode argument: RTLD_GLOBAL Symbols exported from this shared library object will not be available sl@0: for the processing of relocation addresses of any other shared library object. RTLD_LOCAL Symbols exported from this shared library object will not be available sl@0: for the processing of relocation of addresses in any other shared library object. sl@0: sl@0: If path argument contains a slash character the entire argument is used sl@0: as the pathname for the file. C: is considered to be the root and C:\\ is prefixed sl@0: to the path argument to locate the shared library object. If path contains just the name of the shared library to be loaded, the sl@0: default location is sys\\bin. The string in the path argument is limited to a maximum of 256 characters. sl@0: sl@0: dlopen returns the handle for the dynamic library loaded into the address space sl@0: of the current process. sl@0: sl@0: dlsym function returns the address binding of the symbol associated sl@0: with the ordinal number. The NULL-terminated character string symbol contains the ordinal number (address lookup is based on ordinal sl@0: number). The symbols exported by shared DLLs added to the address space by dlopen can be accessed only through calls to dlsym. sl@0: sl@0: Symbol names per se are not searched. Instead dlsym locates the ordinal number corresponding to a symbol name and sl@0: returns the address of the memory location where the symbol is loaded. Ordinal sl@0: numbers therefore form the basis of the name lookup. Since all handles have sl@0: to be identified explicitly (that is, as returned by dlopen ), dlsym returns NULL when presented with special handles such as RTLD_NEXT, sl@0: RTLD_SELF and RTLD_DEFAULT. The implementation treats a NULL handle passed to dlsym as an error and returns NULL. sl@0: sl@0: The dlsym function returns a null pointer if the symbol (ordinal) cannot sl@0: be found and sets an error condition which may be queried with dlerror. sl@0: sl@0: The dlerror function sl@0: returns a null-terminated character string describing the last error that sl@0: occurred during a call to dlopen, dlsym, sl@0: or dlclose. sl@0: If no such error has occurred, dlerror returns a null pointer. sl@0: At each call to dlerror, sl@0: the error indication is reset. sl@0: Thus in the case of two calls sl@0: to dlerror, sl@0: where the second call follows the first immediately, the second call sl@0: will always return a null pointer. sl@0: sl@0: The dlclose function deletes a reference to the DLL referenced by handle. If the reference count drops to 0, the DLL is removed from the sl@0: address space and handle is rendered invalid. Just before removing the DLL from the current sl@0: process's address space the destructors of the DLL's global objects sl@0: are invoked. If dlclose is successful it returns 0. Otherwise it returns -1 and sets sl@0: an error condition that can be interrogated with dlerror. sl@0: sl@0: sl@0: sl@0: Notes: sl@0: sl@0: The ordinal numbers associated with the functions in a DLL are in the DLL's sl@0: .def file. sl@0: sl@0: sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn dlsym(void * handle, const char * symbol) sl@0: @param handle sl@0: @param symbol sl@0: Refer to dlopen() for the documentation sl@0: sl@0: sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: sl@0: /** @fn dlerror(void) sl@0: sl@0: Refer to dlopen() for the documentation sl@0: sl@0: sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: /** @fn dlclose(void *handle) sl@0: @param handle sl@0: Refer to dlopen() for the documentation sl@0: sl@0: sl@0: sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: sl@0: sl@0: /** @def RTLD_LAZY sl@0: sl@0: Modes and flags for dlopen(). Bind function calls lazily. sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: sl@0: /** @def RTLD_NOW sl@0: sl@0: Modes and flags for dlopen(). Bind function calls immediately. sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: sl@0: /** @def RTLD_GLOBAL sl@0: sl@0: Modes and flags for dlopen(). Make symbols globally available. sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: sl@0: /** @def RTLD_LOCAL sl@0: sl@0: Modes and flags for dlopen(). Opposite of RTLD_GLOBAL, and the default. sl@0: sl@0: @publishedAll sl@0: @externallyDefinedApi sl@0: */ sl@0: sl@0: sl@0: /** @def RTLD_NEXT sl@0: sl@0: Special handle arguments for dlsym()/dlinfo(). Search subsequent objects. sl@0: sl@0: @publishedAll sl@0: @released sl@0: */ sl@0: sl@0: sl@0: /** @def RTLD_DEFAULT sl@0: sl@0: Special handle arguments for dlsym()/dlinfo(). Use default search algorithm. sl@0: sl@0: @publishedAll sl@0: @released sl@0: */ sl@0: sl@0: sl@0: /** @def RTLD_SELF sl@0: sl@0: Special handle arguments for dlsym()/dlinfo(). Search the caller itself. sl@0: sl@0: @publishedAll sl@0: @released sl@0: */ sl@0: sl@0: