OSDynLoad_FindExport

Syntax

#include <cafe/os/OSDynLoad.h>

int OSDynLoad_FindExport(OSDynLoad_ModuleHandle aModuleHandle, 
                         int                    aTypeIsData, 
                         char const *           apExportName, 
                         void * *               appRetAddr);

Parameters

aModuleHandle Handle of the loaded module holding the symbol you want to find.
aTypeIsData Flag indicating whether you want to look for a code or data symbol. Set to nonzero to look for data, zero to look for code.
apExportName Pointer to the ASCII string containing the name of the export you are looking for.
appRetAddr Pointer to the pointer to receive the address of the symbol inside the specified module.

Return Values

Returns an OSDYNLOAD_ERR_xxx error code (see OSDynLoad.h).

Description

Finds code or data exported by a loaded RPL.

The search for the export proceeds in Log2N time, where N is the number of code or data symbols being exported by the RPL.

OSDynLoad_FindExport is required when accessing a symbol defined in another module, but the calling module did not link against the import library of the module that owns the symbol.

In this way, exported symbols can be shared at runtime. This applies to relationships between two RPLs or between an RPL and an RPX.

NOTE:
This function cannot be used to share a symbol between two RPXs.

To use OSDynLoad_FindExport, the desired symbol must be exported at link time by the module that owns it. For information on how to export symbols, see the following.

OSDynLoad_FindExport is also the recommended method to address the issue of cross-referencing between RPLs.

Example

In this example, an RPL module exports some symbols; a different module uses OSDynLoad_FindExport to "find" the symbols and access them at runtime.

Exporting the Symbols

In the first step, ensure that the desired symbols are exported from the module within which they are defined. Consider the following example module, which defines the symbols foo and bar:

// this module defines "foo" and "bar"
int foo;

void bar()
{
    foo++;
}

To export them, locate the module's export symbol definition file and insert the names foo and bar. For information on how to export symbols, see the tools preprpl[32|64] and makerpl[32|64].

Using the Symbols from Another Module

For the module that will use foo and bar, do the following:

  1. Create a pointer to a function type for all desired code symbols:
    typedef void (*pf_bar)();
    
  2. Create auto, static, or global variables (depending on your scope requirements) for each symbol:
    pf_bar  char1_bar;
    int    *char1_foo;
    
  3. Acquire a handle to the module that exported the symbols. See OSDynLoad_Acquire for details.
    int                     err = 0;
    OSDynLoad_ModuleHandle  hCharModule;
    
    err = OSDynLoad_Acquire("char1.rpl", &hCharModule);
    if (err)
    {
       OSReport("Load of module \"%s\" failed. err = 0x%08X\n", "char1.rpl", err);
       return err;
    }
    
    NOTE:
    If the exporting module has already been loaded, then OSDynLoad_Acquire returns the existing handle.

  4. Call OSDynLoad_FindExport to find all of the necessary symbols:
    // load char1's foo and bar
    // pass nonzero for data
     err = OSDynLoad_FindExport(hCharModule, 1, "foo", (void **)&char1_foo);
     if (err)
     {
         OSReport("could not find 'foo' in \"%s\". err = 0x%08X\n", "char1.rpl", err);
         OSDynLoad_Release(hCharModule);
         return err;
     }
     // pass zero for code
     err = OSDynLoad_FindExport(hCharModule, 0, "bar", (void **)&char1_bar);
     if (err)
     {
         OSReport("could not find 'bar' in \"%s\". err = 0x%08X\n", "char1.rpl", err);
         OSDynLoad_Release(hCharModule);
         return err;
     }            
    
  5. Access the symbols indirectly:
    OSReport("char1's foo is %d; expected 1\n", *char1_foo);
    OSReport("increment foo from RPX\n");
    (*char1_foo)++;
    OSReport("bar increments foo\n");
    char1_bar();
    OSReport("char1's foo is %d; expected 3\n", *char1_foo);
    

The examplemake demo also illustrates the use of OSDynLoad_FindExport.

Do Not Call From

None.

See Also

OSDynLoad_Acquire
OSDynLoad_AddNotifyCallback
OSDynLoad_DelNotifyCallback
OSDynLoad_GetAllocator
OSDynLoad_GetModuleName
OSDynLoad_IsModuleLoaded
OSDynLoad_Release
OSDynLoad_SetAllocator
Building with Examplemake
RPX/RPL Cross-Referencing

Revision History

2013/11/01 Added OSDynLoad_IsModuleLoaded.
2013/05/08 Automated cleanup pass.
2011/10/19 Added Examplemake.
2011/03/11 Initial version.


CONFIDENTIAL